pept.tracking.Minpoints

class pept.tracking.Minpoints(num_lines, max_distance, cutoffs=None, append_indices=False)[source]

Bases: pept.base.pipelines.LineDataFilter

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

Given a sample of lines, the minpoints are the minimum distance points (MDPs) for every possible combination of num_lines lines that satisfy the following conditions:

  1. Are within the cutoffs.

  2. Are closer to all the constituent LoRs than max_distance.

Under typical usage, the Minpoints class is initialised with a pept.LineData instance, automatically calculating the minpoints from the samples of lines. The Minpoints class inherits from pept.PointData, such that once the cutpoints have been computed, all the methods from the parent class pept.PointData can be used on them (such as visualisation functionality).

For more control over the operations, pept.tracking.peptml.find_minpoints can be used - it receives a generic numpy array of LoRs (one ‘sample’) and returns a numpy array of cutpoints.

See also

pept.LineData

Encapsulate LoRs for ease of iteration and plotting.

pept.tracking.peptml.HDBSCANClusterer

Efficient, parallel HDBSCAN-based clustering of cutpoints.

pept.scanners.ParallelScreens

Read in and initialise a pept.LineData instance from parallel screens PET/PEPT detectors.

pept.utilities.read_csv

Fast CSV file reading into numpy arrays.

Notes

Once instantiated with a LineData, the class computes the minpoints and automatically sets the sample_size to the average number of minpoints found per sample of LoRs.

Examples

Compute the minpoints for a LineData instance for all triplets of lines that are less than 0.1 from those lines:

>>> line_data = pept.LineData(example_data)
>>> minpts = peptml.Minpoints(line_data, 3, 0.1)

Compute the minpoints for a single sample:

>>> sample = line_data[0]
>>> cutpts_sample = peptml.find_minpoints(sample, 3, 0.1)
Attributes
line_datainstance of pept.LineData

The LoRs for which the cutpoints will be computed. It must be an instance of pept.LineData.

num_lines: int

The number of lines in each combination of LoRs used to compute the MDP. This function considers every combination of num_lines from the input sample_lines. It must be smaller or equal to the number of input lines sample_lines.

max_distance: float

The maximum allowed distance between an MDP and its constituent lines. If any distance from the MDP to one of its lines is larger than max_distance, the MDP is thrown away. A good starting value would be 0.1 mm for small tracers and/or clean data, or 0.2 mm for larger tracers and/or noisy data.

cutoffslist-like of length 6

A list (or equivalent) of the cutoff distances for every axis, formatted as [x_min, x_max, y_min, y_max, z_min, z_max]. Only the minpoints which fall within these cutoff distances are considered. The default is None, in which case they are automatically computed using pept.tracking.peptml.get_cutoffs.

sample_size, overlap, number_of_lines, etc.inherited from pept.PointData

Additional attributes and methods are inherited from the base class PointData. Check its documentation for more information.

Methods

find_minpoints(line_data, num_lines, max_distance, cutoffs = None, append_indices = False, max_workers = None, verbose = True)

Compute the minpoints from the samples in a LineData instance.

sample, to_csv, plot, etc.

(inherited from pept.PointData) Additional attributes and methods are inherited from the base class PointData. Check its documentation for more information.
__init__(num_lines, max_distance, cutoffs=None, append_indices=False)[source]

Cutpoints class constructor.

Parameters
line_datainstance of pept.LineData

The LoRs for which the cutpoints will be computed. It must be an instance of pept.LineData.

num_lines: int

The number of lines in each combination of LoRs used to compute the MDP. This function considers every combination of num_lines from the input sample_lines. It must be smaller or equal to the number of input lines sample_lines.

max_distance: float

The maximum allowed distance between an MDP and its constituent lines. If any distance from the MDP to one of its lines is larger than max_distance, the MDP is thrown away. A good starting value would be 0.1 mm for small tracers and/or clean data, or 0.2 mm for larger tracers and/or noisy data.

cutoffslist-like of length 6, optional

A list (or equivalent) of the cutoff distances for every axis, formatted as [x_min, x_max, y_min, y_max, z_min, z_max]. Only the minpoints which fall within these cutoff distances are considered. The default is None, in which case they are automatically computed using pept.tracking.peptml.get_cutoffs.

append_indicesbool, default False

If set to True, the indices of the individual LoRs that were used to compute each minpoint are also appended to the returned array.

max_workersint, optional

The maximum number of threads that will be used for asynchronously computing the minpoints from the samples of LoRs in line_data.

verbosebool, default True

Provide extra information when computing the cutpoints: time the operation and show a progress bar.

Raises
TypeError

If line_data is not an instance of pept.LineData.

ValueError

If 2 <= num_lines <= len(sample_lines) is not satisfied.

ValueError

If cutoffs is not a one-dimensional array with values formatted as [min_x, max_x, min_y, max_y, min_z, max_z].

Methods

__init__(num_lines, max_distance[, cutoffs, …])

Cutpoints 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_lines)

load(filepath)

Load a saved / pickled PEPTObject object from filepath.

save(filepath)

Save a PEPTObject instance as a binary pickle object.

Attributes

append_indices

cutoffs

max_distance

num_lines

copy(deep=True)

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

fit(line_data: collections.abc.Iterable[pept.base.line_data.LineData], 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")
property num_lines
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")
property max_distance
property cutoffs
property append_indices
fit_sample(sample_lines)[source]
pept.tracking.Cutpoints pept.tracking.HDBSCAN