compute_path_sinuosity#

movement.kinematics.compute_path_sinuosity(data, nan_warn_threshold=0.2)[source]#

Compute the sinuosity of a path.

Sinuosity (S) quantifies the tortuosity of a path by combining turning angle statistics with step-length variability. Higher values indicate more tortuous movement. A perfectly straight path has S = 0.

The corrected sinuosity index (Eq. 8 in [1]) is defined as:

\[S = 2\left[\bar{p}\left( \frac{1+\bar{c}}{1-\bar{c}} + b^{2} \right)\right]^{-1/2}\]

where \(\bar{p}\) is the mean step length, \(\bar{c} = \tfrac{1}{n}\sum_{i=1}^{n}\cos(\phi_i)\) is the mean cosine of turning angles, and \(b = \mathrm{SD}(p_i)\,/\,\bar{p}\) is the coefficient of variation of step length.

Parameters:

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

  • 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 sinuosity, with dimensions matching those of the input data, except time and space are removed.

Return type:

DataArray

See also

compute_path_length

Total distance travelled along a path.

compute_path_straightness

Net displacement divided by path length.

compute_turning_angle

Step-wise turning angle along a path.

compute_path_emax

Directional-persistence measure.

Notes

Step lengths are computed as the norm of backward displacement vectors via compute_norm() and compute_backward_displacement(). Turning angles are computed via compute_turning_angle().

NaN positions propagate to NaN step lengths and turning angles; the statistics are then computed over the remaining valid samples. An entirely stationary track, or one with all NaN values, will produce NaN sinuosity.

Sinuosity has units of \(1/\sqrt{\text{length}}\), so its numerical value depends on the position units of the input data. Values are not directly comparable across datasets recorded in different spatial units.

References

Examples

>>> from movement.kinematics import compute_path_sinuosity

Compute sinuosity for the centroid trajectory of a poses dataset ds:

>>> centroid = ds.position.mean(dim="keypoint")
>>> sinuosity = compute_path_sinuosity(centroid)

Compute sinuosity over a specific time window:

>>> sinuosity = compute_path_sinuosity(centroid.sel(time=slice(0, 100)))