pept.tracking.BirminghamMethod#

class pept.tracking.BirminghamMethod(fopt=0.5, get_used=False)[source]#

Bases: LineDataFilter

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

Two main methods are provided: fit_sample for tracking a single numpy array of LoRs (i.e. a single sample) and fit which tracks all the samples encapsulated in a pept.LineData class in parallel.

For the given sample of LoRs (a numpy.ndarray), this function minimises the distance between all of the LoRs, rejecting a fraction of lines that lie furthest away from the calculated distance. The process is repeated iteratively until a specified fraction (fopt) of the original subset of LORs remains.

This class is a wrapper around the birmingham_method subroutine (implemented in C), providing tools for asynchronously tracking samples of LoRs. It can return PointData classes which can be easily manipulated and visualised.

See also

pept.LineData

Encapsulate LoRs for ease of iteration and plotting.

pept.PointData

Encapsulate points for ease of iteration and plotting.

pept.utilities.read_csv

Fast CSV file reading into numpy arrays.

PlotlyGrapher

Easy, publication-ready plotting of PEPT-oriented data.

pept.scanners.ParallelScreens

Initialise a pept.LineData instance from parallel screens PEPT detectors.

Examples

A typical workflow would involve reading LoRs from a file, instantiating a BirminghamMethod class, tracking the tracer locations from the LoRs, and plotting them.

>>> import pept
>>> from pept.tracking.birmingham_method import BirminghamMethod

>>> lors = pept.LineData(...)   # set sample_size and overlap appropriately
>>> bham = BirminghamMethod()
>>> locations = bham.fit(lors)  # this is a `pept.PointData` instance

>>> grapher = PlotlyGrapher()
>>> grapher.add_points(locations)
>>> grapher.show()
Attributes
foptfloat

Floating-point number between 0 and 1, representing the target fraction of LoRs in a sample used to locate a tracer.

get_usedbool, default False

If True, attach an attribute ._lines to the output PointData containing the sample of LoRs used (+ a column used).

__init__(fopt=0.5, get_used=False)[source]#

BirminghamMethod class constructor.

foptfloat, default 0.5

Float number between 0 and 1, representing the fraction of remaining LORs in a sample used to locate the particle.

verbosebool, default False

Print extra information when initialising this class.

Methods

__init__([fopt, get_used])

BirminghamMethod class constructor.

copy([deep])

Create a deep copy of an instance of this class, including all inner attributes.

fit(line_data[, executor, max_workers, verbose])

Apply self.fit_sample (implemented by subclasses) according to the execution policy.

fit_sample(sample)

Use the Birmingham method to track a tracer location from a numpy array (i.e.

load(filepath)

Load a saved / pickled PEPTObject object from filepath.

save(filepath)

Save a PEPTObject instance as a binary pickle object.
fit_sample(sample)[source]#

Use the Birmingham method to track a tracer location from a numpy array (i.e. one sample) of LoRs.

For the given sample of LoRs (a numpy.ndarray), this function minimises the distance between all of the LoRs, rejecting a fraction of lines that lie furthest away from the calculated distance. The process is repeated iteratively until a specified fraction (fopt) of the original subset of LORs remains.

Parameters
sample(N, M>=7) numpy.ndarray

The sample of LORs that will be clustered. Each LoR is expressed as a timestamps and a line defined by two points; the data columns are then [time, x1, y1, z1, x2, y2, z2, extra…].

Returns
locationsnumpy.ndarray or pept.PointData

The tracked locations found.

usednumpy.ndarray, optional

If get_used is true, then also return a boolean mask of the LoRs used to compute the tracer location - that is, a vector of the same length as sample, containing 1 for the rows that were used, and 0 otherwise. [Used for multi-particle tracking, not implemented yet].

Raises
ValueError

If sample is not a numpy array of shape (N, M), where M >= 7.

copy(deep=True)#

Create a deep copy of an instance of this class, including all inner attributes.

fit(line_data, executor='joblib', max_workers=None, verbose=True)#

Apply self.fit_sample (implemented by subclasses) according to the execution policy. Simply return a list of processed samples. If you need a reduction step (e.g. stack all processed samples), apply it in the subclass.

static load(filepath)#

Load a saved / pickled PEPTObject object from filepath.

Most often the full object state was saved using the .save method.

Parameters
filepathfilename or file handle

If filepath is a path (rather than file handle), it is relative to where python is called.

Returns
pept.PEPTObject subclass instance

The loaded object.

Examples

Save a LineData instance, then load it back:

>>> lines = pept.LineData([[1, 2, 3, 4, 5, 6, 7]])
>>> lines.save("lines.pickle")

>>> lines_reloaded = pept.LineData.load("lines.pickle")
save(filepath)#

Save a PEPTObject instance as a binary pickle object.

Saves the full object state, including inner attributes, in a portable binary format. Load back the object using the load method.

Parameters
filepathfilename or file handle

If filepath is a path (rather than file handle), it is relative to where python is called.

Examples

Save a LineData instance, then load it back:

>>> lines = pept.LineData([[1, 2, 3, 4, 5, 6, 7]])
>>> lines.save("lines.pickle")

>>> lines_reloaded = pept.LineData.load("lines.pickle")