compute_path_length#

movement.kinematics.compute_path_length(data, nan_policy='interpolate', nan_warn_threshold=0.2)[source]#

Compute the length of a path travelled.

The path length is defined as the sum of the norms (magnitudes) of the displacement vectors between consecutive time points in the data.

Parameters:

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

  • nan_policy (Literal['interpolate', 'omit']) – Policy for handling NaN (missing) values. By default ("interpolate"), a missing segment is assumed to be travelled in a straight line between the two valid positions flanking it. If "omit", missing segments are instead skipped entirely. See Notes 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%).

Returns:

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

Return type:

DataArray

Notes

  1. Handling missing values: By default (nan_policy="interpolate"), a missing segment is assumed to be travelled in a straight line between the two valid positions flanking it. This is implemented under the hood using xarray.DataArray.ffill() (forward-fill), which gives the same segment-length sum as linearly interpolating over the gap. Missing values at the beginning of a path cannot be forward-filled and are still skipped. Choosing nan_policy="omit" makes no such assumption: it sums the lengths of the segments between consecutive valid positions only. A missing position invalidates the two segments on either side of it (the arriving and departing steps), which are omitted from the sum. Both policies underestimate the true path length in the presence of gaps, but "interpolate" less so. For more control over handling missing values, use interpolate_over_time() before calling this function.

  2. Sampling rate sensitivity (‘coastline paradox’): The measured path length is sensitive to the temporal sampling rate (i.e., frames per second) of the tracking data. Higher sampling rates capture finer micro-movements and tracking jitter, which inherently increases the total measured path length. Exercise caution when comparing path lengths across datasets with different temporal resolutions.

See also

compute_path_straightness

A related metric that quantifies the straightness of a path.

Examples

>>> from movement.kinematics import compute_path_length

Compute the path length from the centroid trajectory of a poses dataset ds:

>>> centroid = ds.position.mean(dim="keypoint")
>>> length = compute_path_length(centroid)

Compute path length over a specific time window:

>>> length = compute_path_length(centroid.sel(time=slice(0, 100)))

Skip (omit) missing positions instead of interpolating over them:

>>> length = compute_path_length(centroid, nan_policy="omit")

Examples using compute_path_length#

Compute and visualise kinematics

Compute and visualise kinematics