compute_path_straightness#

movement.kinematics.compute_path_straightness(data, nan_warn_threshold=0.2)[source]#

Compute the straightness index of a path \((D/L)\).

The straightness index is the ratio of the Euclidean distance \(D\) between the first and last valid positions of a trajectory to the total path length \(L\). Values range from 0 to 1, where 1 indicates a perfectly straight path and 0 indicates the individual returned to its starting point. Returns NaN if the path length is zero (e.g. the individual never moves, or there is only one valid position) or if there are no valid positions (e.g. all positions are NaN).

Parameters:

data (DataArray) – The input data containing position information, with time and space (in Cartesian coordinates) as required dimensions.
nan_warn_threshold (float) – If any point track in the data has at least (\(\ge\)) this proportion of values missing, a warning will be emitted. Defaults to 0.2 (20%).

Returns:

An xarray DataArray containing the computed straightness index, with dimensions matching those of the input data, except time and space are removed.

Return type:

DataArray

See also

compute_path_length: The underlying function used to compute the path length \(L\).
compute_path_sinuosity: A related turning-angle-based measure of path tortuosity.
compute_path_emax: An alternative straightness measure derived from the turning-angle distribution which, unlike the \(D/L\) ratio, does not depend on the number of steps in the path.

Notes

The Euclidean distance \(D\), also known as the “straight-line” or “beeline” distance, is calculated using the first and last valid (non-NaN) spatial coordinates in the data. This ensures that missing data at the first or last time points do not nullify the result, provided there are valid observed positions in between.

The total path length \(L\) is computed as in compute_path_length() with nan_policy="interpolate", i.e. each missing segment is assumed to be travelled in a straight line between the two valid positions flanking it. For other ways of filling gaps, use interpolate_over_time() before calling this function.

Note that the total path length \(L\), and therefore the straightness index, is sensitive to the temporal sampling rate (i.e. frames per second), as described in the Notes of compute_path_length().

Examples

>>> from movement.kinematics import compute_path_straightness

Compute the straightness index from the centroid trajectory of a poses dataset ds:

>>> centroid = ds.position.mean(dim="keypoint")
>>> si = compute_path_straightness(centroid)

Compute straightness over a specific time window:

>>> si = compute_path_straightness(centroid.sel(time=slice(0, 100)))