pept.utilities.find_cutpoints#

pept.utilities.find_cutpoints(const double[:, :] sample_lines, double max_distance, const double[:] cutoffs, bool append_indices=0)#

Compute the cutpoints from a given array of lines.

Function signature:
    find_cutpoints(
        double[:, :] sample_lines,  # LoRs in sample
        double max_distance,        # Max distance between two LoRs
        double[:] cutoffs,          # Spatial cutoff for cutpoints
        bint append_indices = False # Append LoR indices used
    )

This is a low-level Cython function that does not do any checks on the input data - it is meant to be used in other modules / libraries. For a normal user, the pept.tracking.peptml function find_cutpoints and class Cutpoints are recommended as higher-level APIs. They do check the input data and are easier to use (for example, they automatically compute the cutoffs).

A cutpoint is the point in 3D space that minimises the distance between any two lines. For any two non-parallel 3D lines, this point corresponds to the midpoint of the unique segment that is perpendicular to both lines.

This function considers every pair of lines in sample_lines and returns all the cutpoints that satisfy the following conditions:

  1. The distance between the two lines is smaller than max_distance.

  2. The cutpoints are within the cutoffs.

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

The sample of lines, where each row is [time, x1, y1, z1, x2, y2, z2], containing two points [x1, y1, z1] and [x2, y2, z2] defining an LoR.

max_distancefloat

The maximum distance between two LoRs for their cutpoint to be considered.

cutoffs(6,) numpy.ndarray

Only consider the cutpoints that fall within the cutoffs. cutoffs has the format [min_x, max_x, min_y, max_y, min_z, max_z].

append_indicesbool, optional

If set to True, the indices of the individual LoRs that were used to compute each cutpoint is also appended to the returned array. Default is False.

Returns
cutpoints(M, 4) or (M, 6) numpy.ndarray

A numpy array of the calculated weighted cutpoints. If append_indices is False, then the columns are [time, x, y, z]. If append_indices is True, then the columns are [time, x, y, z, i, j], where i and j are the LoR indices from sample_lines that were used to compute the cutpoints. The time is the average between the timestamps of the two LoRs that were used to compute the cutpoint. The first column (for time) is sorted.

Examples

>>> import numpy as np
>>> from pept.utilities import find_cutpoints
>>>
>>> lines = np.random.random((500, 7)) * 500
>>> max_distance = 0.1
>>> cutoffs = np.array([0, 500, 0, 500, 0, 500], dtype = float)
>>>
>>> cutpoints = find_cutpoints(lines, max_distance, cutoffs)