Tracking Algorithms (pept.tracking)#

Tracer location, identification and tracking algorithms.

The pept.tracking subpackage hosts different tracking algorithms, working with both the base classes, as well as with generic NumPy arrays.

All algorithms here are either pept.base.Filter or pept.base.Reducer subclasses, implementing the .fit and .fit_sample methods; here is an example using PEPT-ML:

>>> from pept.tracking import *
>>> cutpoints = Cutpoints(0.5).fit(lines)
>>> clustered = HDBSCAN(0.15).fit(cutpoints)
>>> centres = (SplitLabels() + Centroids() + Stack()).fit(clustered)

Once the processing steps have been tuned (see the Tutorials), you can chain all filters into a pept.Pipeline for efficient, parallel execution:

>>> pipeline = (
>>>     Cutpoints(0.5) +
>>>     HDBSCAN(0.15) +
>>>     SplitLabels() + Centroids() + Stack()
>>> )
>>> centres =

If you would like to implement a PEPT algorithm, all you need to do is to subclass a pept.base.Filter and define the method .fit_sample(sample) - and you get parallel execution and pipeline chaining for free!

>>> import pept
>>> class NewAlgorithm(pept.base.LineDataFilter):
>>>     def __init__(self, setting1, setting2 = None):
>>>         self.setting1 = setting1
>>>         self.setting2 = setting2
>>>     def fit_sample(self, sample: pept.LineData):
>>>         processed_points = ...
>>>         return pept.PointData(processed_points)

Tracking Optimisation#

pept.tracking.Debug([verbose, max_samples])

Print types and statistics about the objects being processed in a pept.Pipeline.

pept.tracking.OptimizeWindow(ideal_elems[, ...])

Automatically determine optimum adaptive time window to have an ideal number of elements per sample.

General-Purpose Transformers#

pept.tracking.Stack([sample_size, overlap])

Stack iterables - for example a list[pept.LineData] into a single pept.LineData, a list[list] into a flattened list.

pept.tracking.SplitLabels([remove_labels, ...])

Split a sample of data into unique label values, optionally removing noise and extracting _lines attributes.


alias of GroupBy


Stack all samples and split them into a list according to a named / numeric column index.

pept.tracking.Centroids([error, ...])

Compute the geometric centroids of a list of samples of points.

pept.tracking.LinesCentroids([remove, ...])

Compute the minimum distance point of some pept.LineData while iteratively removing a fraction of the furthest lines.


Select only data satisfying multiple conditions, given as a string, a function or list thereof; e.g.


Select only samples satisfying multiple conditions, given as a string, a function or list thereof; e.g.


Remove columns (either column names or indices) from pept.LineData or pept.PointData.

pept.tracking.Swap(*swaps[, inplace])

Swap two columns in a LineData or PointData.

Space Transformers#

pept.tracking.Voxelize(number_of_voxels[, ...])

Asynchronously voxelize samples of lines from a pept.LineData.

pept.tracking.Interpolate(timestep[, ...])

Interpolate between data points at a fixed sampling rate; useful for Eulerian fields computation.

pept.tracking.Reorient([dimensions, basis, ...])

Rotate a dataset such that it is oriented according to its principal axes.

pept.tracking.OutOfViewFilter([max_time, k])

Remove tracer locations that are sparse in time - ie the k-th nearest detection is later than max_time.

pept.tracking.RemoveStatic(time_window, ...)

Remove parts of a PointData where the tracer remains static.

Tracer Locating Algorithms#

pept.tracking.BirminghamMethod([fopt, get_used])

The Birmingham Method is an efficient, analytical technique for tracking tracers using the LoRs from PEPT data.

pept.tracking.Cutpoints(max_distance[, ...])

Transform LoRs (a pept.LineData instance) into cutpoints (a pept.PointData instance) for clustering, in parallel.

pept.tracking.Minpoints(num_lines, max_distance)

Transform LoRs (a pept.LineData instance) into minpoints (a pept.PointData instance) for clustering, in parallel.

pept.tracking.HDBSCAN(true_fraction[, ...])

Use HDBSCAN to cluster some pept.PointData and append a cluster label to each point.

pept.tracking.FPI([w, r, lld_counts, verbose])

FPI is a modern voxel-based tracer-location algorithm that can reliably work with unknown numbers of tracers in fast and noisy environments.

Trajectory Separation Algorithms#

pept.tracking.Segregate(window, cut_distance)

Segregate the intertwined points from multiple trajectories into individual paths.

pept.tracking.Reconnect(tmax, dmax[, ...])

Best-fit trajectory segment reconstruction based on time, distance and arbitrary tracer signatures.

Time Of Flight Algorithms#


Compute the positron annihilation locations of each LoR as given by the Time Of Flight (ToF) data of the two LoR timestamps.

pept.tracking.CutpointsToF([max_distance, ...])

Compute cutpoints from all pairs of lines whose Time Of Flight-predicted locations are closer than max_distance.


Append weights according to the Gaussian distribution that best fits the samples of points.

Post Processing Algorithms#

pept.tracking.Velocity(window[, degree, ...])

Append the dimension-wise or absolute velocity to samples of points using a 2D fitted polynomial in a rolling window mode.