trackpy.link_df¶

trackpy.link_df(features, search_range, memory=0, neighbor_strategy='KDTree', link_strategy='auto', predictor=None, adaptive_stop=None, adaptive_step=0.95, copy_features=False, diagnostics=False, pos_columns=None, t_column=None, hash_size=None, box_size=None, verify_integrity=True, retain_index=False)¶

Link features into trajectories, assigning a label to each trajectory.

Parameters:

Parameters:	features : 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. After linking, this DataFrame will contain a ‘particle’ column. search_range : float the maximum distance features can move between frames memory : integer the maximum number of frames during which a feature can vanish, then reppear nearby, and be considered the same particle. 0 by default. neighbor_strategy : {‘KDTree’, ‘BTree’} algorithm used to identify nearby features 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 predictor : function, 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_stop : float, 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_step : float, optional Reduce search_range by multiplying it by this factor. copy_features : boolean Leave the original features DataFrame intact (slower, uses more memory) diagnostics : boolean Collect details about how each particle was linked, and return as columns in the output DataFrame. Implies copy=True. pos_columns : DataFrame column names (unlimited dimensions) Default is [‘x’, ‘y’] t_column : DataFrame column name Default is ‘frame’ hash_size : sequence For ‘BTree’ mode only. Define the shape of the search region. If None (default), infer shape from range of data. box_size : sequence For ‘BTree’ mode only. Define the parition size to optimize performance. If None (default), the search_range is used, which is a reasonable guess for best performance. verify_integrity : boolean False by default for fastest performance. Use True if you suspect a bug in linking. retain_index : boolean By default, the index is reset to be sequential. To keep the original index, set to True. Default is fine unless you devise a special use.
Returns:	trajectories : DataFrame This is the input features DataFrame, now with a new column labeling each particle with an ID number. This is not a copy; the original features DataFrame is modified.

features : 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. After linking, this DataFrame will contain a ‘particle’ column.

search_range : float

the maximum distance features can move between frames

memory : integer

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

neighbor_strategy : {‘KDTree’, ‘BTree’}

algorithm used to identify nearby features

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

predictor : function, 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_stop : float, 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_step : float, optional

Reduce search_range by multiplying it by this factor.

copy_features : boolean

Leave the original features DataFrame intact (slower, uses more memory)

diagnostics : boolean

Collect details about how each particle was linked, and return as columns in the output DataFrame. Implies copy=True.

pos_columns : DataFrame column names (unlimited dimensions)

Default is [‘x’, ‘y’]

t_column : DataFrame column name

Default is ‘frame’

hash_size : sequence

For ‘BTree’ mode only. Define the shape of the search region. If None (default), infer shape from range of data.

box_size : sequence

For ‘BTree’ mode only. Define the parition size to optimize performance. If None (default), the search_range is used, which is a reasonable guess for best performance.

verify_integrity : boolean

False by default for fastest performance. Use True if you suspect a bug in linking.

retain_index : boolean

By default, the index is reset to be sequential. To keep the original index, set to True. Default is fine unless you devise a special use.

Returns:

trajectories : DataFrame

This is the input features DataFrame, now with a new column labeling each particle with an ID number. This is not a copy; the original features DataFrame is modified.