compute_path_emax#

movement.kinematics.compute_path_emax(data, in_spatial_units=True, nan_warn_threshold=0.2)[source]#

Compute the maximum expected displacement (\(E_{\max}\)).

\(E_{\max}\) is a straightness measure that captures the directional persistence of a path. Intuitively, it is the maximum expected displacement of an animal navigating without an external directional reference (e.g. a compass or a landmark), given the observed distribution of its turning angles and step lengths [1]. Larger values indicate straighter, more persistent paths; values close to zero indicate sinuous paths.

Two variants are available. The dimensionless variant \(E_{\max}^{(a)}\) depends only on the turning angles:

\[E_{\max}^{(a)} = \frac{\bar{c}}{1 - \bar{c}}, \qquad \bar{c} = \overline{\cos\theta}\]

where \(\theta\) are the turning angles and \(\bar{c}\) is their mean cosine. The variant \(E_{\max}^{(b)}\) scales this by the mean step length \(\bar{p}\) to express the result in the same spatial units as the input:

\[E_{\max}^{(b)} = \bar{p} \, E_{\max}^{(a)}\]
Parameters:

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

  • in_spatial_units (bool) – If True (the default), return the dimensioned variant \(E_{\max}^{(b)}\), expressed in the same spatial units as data. If False, return the dimensionless variant \(E_{\max}^{(a)}\).

  • 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:

The maximum expected displacement, with dimensions matching those of the input data, except time and space are removed. When in_spatial_units is True the values are in the same spatial units as data; otherwise they are dimensionless.

Return type:

DataArray

See also

compute_turning_angle

The underlying function used to compute the turning angles.

compute_path_sinuosity

A related turning-angle-based measure of path tortuosity.

compute_path_straightness

A related, path-length-based measure of straightness.

Notes

  1. Mean cosine of the turning angles. \(\bar{c} = \overline{\cos\theta}\) is the time average (ignoring NaN values) of the cosine of the turning angles \(\theta\) returned by compute_turning_angle(). The first two time steps have no defined turning angle and so do not contribute.

  2. Range. \(E_{\max}^{(a)} \in [-0.5, \infty)\). While highly sinuous paths actually have values approaching 0, negative values specifically arise for trajectories with a systematic backward-turning bias where the mean cosine \(\bar{c}\) is itself negative.

  3. Straight paths. As a path approaches a perfectly straight line, \(\bar{c} \to 1\), so \(1 - \bar{c} \to 0\) and \(E_{\max} \to +\infty\). An infinite result is therefore the correct, expected output for a straight path.

  4. Missing values. Turning angles and step lengths that are NaN (e.g. from missing positions or stationary steps) are ignored when averaging. If every turning angle is NaN (e.g. a stationary track), the result is NaN.

References

Examples

>>> from movement.kinematics import compute_path_emax

Compute E_max from the centroid trajectory of a poses dataset ds:

>>> centroid = ds.position.mean(dim="keypoint")
>>> emax = compute_path_emax(centroid)

Return the dimensionless variant instead:

>>> emax_a = compute_path_emax(centroid, in_spatial_units=False)

Compute over a specific time window:

>>> emax = compute_path_emax(centroid.sel(time=slice(0, 100)))