spine.utils.tracking

Functions

check_track_orientation(coordinates, values, ...)	Given a set of track point coordinates and the track end points, checks which end point is most likely to be the correct start, based on the rate of energy deposition in the track.
get_track_deposition_gradient(coordinates, ...)	Given a set of point coordinates and their values associated with a track and a start point, compute the deposition gradient with respect to the start point.
get_track_length(coordinates[, ...])	Given a set of point coordinates associated with a track and one of its end points, compute its length.
get_track_segment_dedxs(coordinates, values)	Given a set of point coordinates and their values associated with a track and one of its end points, compute the energy/charge deposition rate as a function of the residual range.
get_track_segments(coordinates, ...)	Given a set of point coordinates associated with a track and one of its end points, divide the track into segments of the requested length.
get_track_spline(coordinates, segment_length)	Estimate the best approximating curve defined by a point cloud using univariate 3D splines.

spine.utils.tracking.get_track_length(coordinates: Array(float32, 2, 'A', False, aligned=True), segment_length: float32 = None, point: Array(float32, 1, 'A', False, aligned=True) = None, method: str = 'bin_pca', anchor_point: bool = True, min_count: int = 10, spline_smooth: float = None) → float32

Given a set of point coordinates associated with a track and one of its end points, compute its length.

Parameters:

• coordinates (np.ndarray) – (N, 3) Coordinates of the points that make up the track

• segment_length (float, optional) – Segment length in the units that specify the coordinates

• point (np.ndarray, optional) –

  3. An end point of the track

• method (str, default 'bin_pca') – Method used to compute the track length (one of ‘displacement’, ‘step’, ‘step_next’, ‘bin_pca’ or ‘spline’)

• anchor_point (bool, default True) – Weather or not to collapse end point onto the closest track point

• min_count (int, default 10) – Minimum number of points in a segment to use it to evaluate the direction of the next step along the track.

• spline_smooth (float, optional) – The smoothing factor to be used in spline regression, when used

Returns:

Total length of the track

Return type:

float

spine.utils.tracking.check_track_orientation(coordinates: Array(float32, 2, 'A', False, aligned=True), values: Array(float32, 1, 'A', False, aligned=True), start_point: Array(float32, 1, 'A', False, aligned=True), end_point: Array(float32, 1, 'A', False, aligned=True), method: str = 'local', anchor_points: bool = True, local_radius: float32 = 5, segment_method: str = 'step_next', segment_length: float32 = 5, segment_min_count: int = 10) → bool

Given a set of track point coordinates and the track end points, checks which end point is most likely to be the correct start, based on the rate of energy deposition in the track.

Parameters:

• coordinates (np.ndarray) – (N, 3) Coordinates of the points that make up the track

• values (np.ndarray) –

  14. Values associated with each point

• start_point (np.ndarray) –

  3. Start point of the track

• end_point (np.ndarray) –

  3. End point of the track

• method (str, default 'local') – Method used to orient the track (one of ‘local’, ‘gradient’)

• local_radius (float, default 5) – Radius around the end points to used to evaluate the local dE/dx

• anchor_points (bool, default True) – Weather or not to collapse end point onto the closest track point

• segment_method (str, default 'step_next') – Method used to segment the track when using the ‘gradient’ method

• segment_length (float, default 5) – Segment length when using the ‘gradient’ method

• segment_min_count (int, default 10) – Minimum number of points in a segment when using the ‘gradient’ method

Returns:

Returns True if the start point provided is correct, False if the end point is more likely to be the start point.

Return type:

bool

spine.utils.tracking.get_track_deposition_gradient(coordinates: Array(float32, 2, 'A', False, aligned=True), values: Array(float32, 1, 'A', False, aligned=True), start_point: Array(float32, 1, 'A', False, aligned=True), segment_length: float32 = 5.0, method: str = 'step_next', anchor_point: bool = True, min_count: int = 10)

Given a set of point coordinates and their values associated with a track and a start point, compute the deposition gradient with respect to the start point.

Parameters:

• coordinates (np.ndarray) – (N, 3) Coordinates of the points that make up the track

• values (np.ndarray) –

  14. Values associated with each point

• start_point (np.ndarray) –

  3. End point of the track

• segment_length (float, default 5) – Segment length in the units that specify the coordinates

• method (str, default 'step_next') – Method used to segment the track (one of ‘step’, ‘step_next’ or ‘bin_pca’)

• anchor_point (bool, default True) – Weather or not to collapse end point onto the closest track point

• min_count (int, default 10) – Minimum number of points in a segment for it to be valid. If not valid, the dedx value for that segment is not used to compute the gradient.

Returns:

• gradient (float) – Deposition gradient along the track from the start point

• segment_dedxs (np.ndarray) –

  19. Array of energy/charge deposition rate values

• segment_rrs (np.ndarray) –

  19. Array of residual ranges (center of the segment w.r.t. end point)

• segment_lengths (np.ndarray) –

  19. Array of segment lengths

spine.utils.tracking.get_track_segment_dedxs(coordinates: Array(float32, 2, 'A', False, aligned=True), values: Array(float32, 1, 'A', False, aligned=True), end_point: Array(float32, 1, 'A', False, aligned=True) = None, segment_length: float32 = 5.0, method: str = 'step_next', anchor_point: bool = True, min_count: int = 10)

Given a set of point coordinates and their values associated with a track and one of its end points, compute the energy/charge deposition rate as a function of the residual range.

Parameters:

• coordinates (np.ndarray) – (N, 3) Coordinates of the points that make up the track

• values (np.ndarray) –

  14. Values associated with each point

• end_point (np.ndarray, optional) –

  3. End point of the track

• segment_length (float, default 5.) – Segment length in the units that specify the coordinates

• method (str, default 'step_next') – Method used to segment the track (one of ‘step’, ‘step_next’ or ‘bin_pca’)

• anchor_point (bool, default True) – Weather or not to collapse end point onto the closest track point

• min_count (int, default 10) – Minimum number of points in a segment for it to be valid. If not valid, the dedx value returned for the segment is -1.

Returns:

• seg_dedxs (np.ndarray) –

  19. Array of energy/charge deposition rate values

• seg_errs (np.ndarray) –

  19. Array of uncertainties on the energy/charge deposition rate

• seg_rrs (np.ndarray) –

  19. Array of residual ranges (center of the segment w.r.t. end point)

• seg_clusts (List[np.ndarray]) –

  19. List of indexes which correspond to each segment cluster of points

• seg_dirs (np.ndarray) – (S, 3) Array of segment direction vectors

• seg_lengths (np.ndarray) –

  19. Array of segment lengths

spine.utils.tracking.get_track_segments(coordinates: Array(float32, 2, 'A', False, aligned=True), segment_length: float32, point: Array(float32, 1, 'A', False, aligned=True) = None, method: str = 'step_next', anchor_point: bool = True, min_count: int = 10) -> (List(array(int64, 1d, A), False), Array(float32, 2, 'A', False, aligned=True), Array(float64, 1, 'A', False, aligned=True))

Given a set of point coordinates associated with a track and one of its end points, divide the track into segments of the requested length.

Parameters:

• coordinates (np.ndarray) – (N, 3) Coordinates of the points that make up the track

• segment_length (float) – Segment length in the units that specify the coordinates

• point (np.ndarray, optional) –

  3. A preferred end point of the track from which to start

• method (str, default 'step_next') – Method used to segment the track (one of ‘step’, ‘step_next’ or ‘bin_pca’)

• anchor_point (bool, default True) – Weather or not to collapse end point onto the closest track point

• min_count (int, default 10) – Minimum number of points in a segment to use it to evaluate the direction of the next step along the track.

Returns:

• segment_clusts (List[np.ndarray]) –

  19. List of indexes which correspond to each segment cluster of points

• segment_dirs (np.ndarray) – (S, 3) Array of segment direction vectors

• segment_lengths (np.ndarray) –

  19. Array of segment lengths

spine.utils.tracking.get_track_spline(coordinates, segment_length, s=None)

Estimate the best approximating curve defined by a point cloud using univariate 3D splines.

The length is computed by measuring the length of the piecewise linear interpolation of the spline at points defined by the bin size.

Parameters:

• coordinatea (np.ndarray) – (N, 3) point cloud

• segment_length (float) – The subdivision length at which to sample points from the spline. If the track length is less than the segment_length, then the returned length will be computed from the farthest two projected points along the track’s principal direction.

• s (float, optional) – The smoothing factor to be used in spline regression, by default None

Returns:

• u (np.ndarray) –

  (N) The principal axis parametrization of the curve C(u) = (spx(u), spy(u), spz(u))

• sppoints (np.ndarray) – (N, 3) The graph of the spline at points u

• splines (scipy.interpolate.UnivariateSpline) – Approximating splines for the point cloud defined by points

• length (float) – The estimate of the total length of the curve