trackpy.link_partial

trackpy.link_partial(f, search_range, link_range, pos_columns=None, t_column='frame', **kwargs)

Patch the trajectories in a DataFrame by linking only a range of frames

A dataset can be divided into several patches (time intervals) and linked separately with this function, for e.g. parallel processing. The results can then be stitched back together with reconnect_traj_patch().

Another application is to link a portion of a dataset again with adjusted parameters.

Parameters:

fDataFrame

The DataFrame must include any number of column(s) for position and a column of frame numbers. By default, ‘x’ and ‘y’ are expected for position, and ‘frame’ is expected for frame number. See below for options to use custom column names.

search_rangefloat or tuple

the maximum distance features can move between frames, optionally per dimension

link_rangetuple of 2 ints

Only frames in the range(start, stop) will be analyzed.

memoryinteger, optional

the maximum number of frames during which a feature can vanish, then reappear nearby, and be considered the same particle. 0 by default.

pos_columnslist of str, optional

Default is [‘y’, ‘x’], or [‘z’, ‘y’, ‘x’] when ‘z’ is present in f

t_columnstr, optional

Default is ‘frame’

predictorfunction, optional

Improve performance by guessing where a particle will be in the next frame. For examples of how this works, see the “predict” module.

adaptive_stopfloat, optional

If not None, when encountering an oversize subnet, retry by progressively reducing search_range until the subnet is solvable. If search_range becomes <= adaptive_stop, give up and raise a SubnetOversizeException.

adaptive_stepfloat, optional

Reduce search_range by multiplying it by this factor.

link_strategy{‘recursive’, ‘nonrecursive’, ‘numba’, ‘drop’, ‘auto’}

algorithm used to resolve subnetworks of nearby particles ‘auto’ uses numba if available ‘drop’ causes particles in subnetworks to go unlinked

Returns:

DataFrame with added column ‘particle’ containing trajectory labels.

The t_column (by default: ‘frame’) will be coerced to integer.

See also

reconnect_traj_patch

Notes

The memory option cannot retain particles at the boundaries between patches. Likewise, if a predictor depends on past trajectories, it may work poorly at the start of each patch.

Examples

We purposely define a DataFrame with erroneously linked particles:

>>> df = pd.DataFrame({
...     'x': [5., 10., 15., 20., 10., 14., 19.],
...     'y': [0., 0., 0, 0., 2., 4., 6.],
...     'particle': [5, 5, 8, 8, 8, 5, 5],
...     'frame': [0, 1, 2, 3, 1, 2, 3]
... })

We can fix the missed link at frame 1 by calling link_partial like so:

>>> link_partial(df, search_range=20., link_range=(1, 2))
      x    y  particle  frame
0   5.0  0.0         5      0
1  10.0  0.0         5      1
4  10.0  2.0         8      1
2  15.0  0.0         5      2
5  14.0  4.0         8      2
3  20.0  0.0         5      3
6  19.0  6.0         8      3

Note that this partial link remapped the particle indices after the link_range. This is done by the function reconnect_traj_patch