compute_directional_change

movement.kinematics.compute_directional_change(data, in_degrees=False, min_step_length=0.0)

Compute the directional change (DC) per time step.

The directional change at step \(i\) is the absolute turning angle divided by the temporal interval spanning the two steps that define it [1]:

\[\mathrm{DC}_i = \frac{|\theta_i|}{\Delta t_i}\]

where \(\theta_i\) is the signed turning angle at step \(i\) and \(\Delta t_i = t_i - t_{i-2}\).

Parameters:

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

• in_degrees (bool) – If True, the turning angles (and hence the directional change) are expressed in degrees rather than radians. Defaults to False.

• min_step_length (float) – The minimum step length used when computing turning angles. Steps shorter than or equal to this value produce NaN turning angles, which propagate to NaN directional change values. The default 0.0 only masks steps with exactly zero length; near-zero steps from positional jitter may still produce spurious turning angles. See compute_turning_angle() for details.

Returns:

Directional change values with the same dimensions as the input, except space is removed. Values are in radians per time unit (e.g. radians/second if time is in seconds), or degrees per time unit if in_degrees is True.

Return type:

DataArray

Notes

Boundary behaviour: The first two time steps of the output are always NaN, because a turning angle requires three consecutive positions (see compute_turning_angle()).

References

[1]

Kitamura, T. & Imafuku, M. (2015). Behavioural mimicry in flight path of Batesian intraspecific polymorphic butterfly Papilio polytes. Proc. R. Soc. B 282(1809). https://doi.org/10.1098/rspb.2015.0483

See also

compute_turning_angle

The underlying function used to compute turning angles.

Examples

>>> from movement.kinematics import compute_directional_change

Compute directional change from the centroid trajectory of a poses dataset ds:

>>> centroid = ds.position.mean(dim="keypoint")
>>> dc = compute_directional_change(centroid)

Compute over a specific time window:

>>> dc = compute_directional_change(centroid.sel(time=slice(0, 100)))

Filter out pose-estimation jitter by setting min_step_length:

>>> dc = compute_directional_change(centroid, min_step_length=3)