compute_path_deviation

movement.kinematics.compute_path_deviation(data)

Compute deviation from the straight-line path at each time point.

For each time point \(t\), the path deviation is the perpendicular (unsigned) distance between the position \(P(t)\) and the infinite straight line passing through the first and last valid positions in the data, denoted \(A\) and \(B\) respectively. Zero means the position lies exactly on the straight line; larger values indicate greater lateral excursion.

Formally, let \(\mathbf{u} = B - A\) be the chord vector and \(\hat{\mathbf{u}} = \mathbf{u} / \|\mathbf{u}\|\) its unit vector. The deviation at time \(t\) is:

\[d(t) = \left\| (P(t) - A) - \left[(P(t) - A) \cdot \hat{\mathbf{u}}\right] \hat{\mathbf{u}} \right\|\]

This is the norm of the component of \(P(t) - A\) that is perpendicular to the chord, and is equivalent to the distance from \(P(t)\) to the infinite line through \(A\) and \(B\). The formulation is dimension-agnostic (works for 2D and 3D data).

Parameters:

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

Returns:

An xarray DataArray containing the perpendicular deviation from the chord at each time point, with dimensions matching those of the input data, except space is removed. Values are in the same spatial units as the input.

Return type:

DataArray

Raises:

ValueError – If fewer than 2 time points exist in the data, or if the chord length is zero (i.e. A == B) for all tracks. If the chord length is zero for some (but not all) tracks, a warning is issued and those tracks will have NaN deviation.

See also

compute_path_length

Total distance travelled along the path.

compute_path_straightness

Ratio of chord length to path length.

Examples

>>> from movement.kinematics import compute_path_deviation

Compute per-frame path deviation from the centroid trajectory of a poses dataset ds:

>>> centroid = ds.position.mean(dim="keypoint")
>>> deviation = compute_path_deviation(centroid)

Compute the maximum lateral excursion over the trajectory:

>>> max_deviation = deviation.max(dim="time")

Compute the mean deviation over a specific time window:

>>> mean_deviation = compute_path_deviation(
...     centroid.sel(time=slice(10, 50))
... ).mean(dim="time")