compute_path_length#

movement.kinematics.compute_path_length(data, start=None, stop=None, nan_policy='ffill', nan_warn_threshold=0.2)[source]#

Compute the length of a path travelled between two time points.

The path length is defined as the sum of the norms (magnitudes) of the displacement vectors between two time points start and stop, which should be provided in the time units of the data array. If not specified, the minimum and maximum time coordinates of the data array are used as start and stop times, respectively.

Parameters:

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

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

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

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

  • nan_warn_threshold (float, optional) – If more than this proportion of values are missing in any point track, 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:

xarray.DataArray

Notes

Choosing nan_policy="ffill" will use xarray.DataArray.ffill() to forward-fill missing segments (NaN values) across time. This equates to assuming that a track remains stationary for the duration of the missing segment and then instantaneously moves to the next valid position, following a straight line. This approach tends to underestimate the path length, and the error increases with the number of missing values.

Choosing nan_policy="scale" will adjust the path length based on the the proportion of valid segments per point track. For example, if only 80% of segments are present, the path length will be computed based on these and the result will be divided by 0.8. This approach assumes that motion dynamics are similar across observed and missing time segments, which may not accurately reflect actual conditions.