compute_path_straightness#

movement.kinematics.compute_path_straightness(data, start=None, stop=None, nan_policy='ffill', 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 animal returned to its starting point. Returns NaN if the path length is zero.

Parameters:

  • data (DataArray) – The input data containing position information, with time and space (in Cartesian coordinates) as required dimensions.

  • start (float | None) – The start time of the path. If None (default), the minimum time coordinate in the data is used.

  • stop (float | None) – The end time of the path. If None (default), the maximum time coordinate in the data is used.

  • nan_policy (Literal['ffill', 'scale']) – Policy to handle NaN (missing) values for the path length computation. Can be one of "ffill" or "scale". Defaults to "ffill" (forward fill). See compute_path_length() for more details on the two policies.

  • 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%). Directly passed to compute_path_length().

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

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 within the specified time window. This ensures that missing data at the exact start or stop boundaries do not nullify the result, provided there are valid observed positions within the slice.

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().

See also

compute_path_length()

The underlying function used to compute the path length \(L\).

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, start=0, stop=100)