add_changepoints_to_ds#

ethograph.io.dataset.add_changepoints_to_ds(ds, target_feature, changepoint_name, changepoint_func, **func_kwargs)[source]#

Detect changepoints in a feature and store them in the dataset.

Applies changepoint_func independently along every non-time dimension (e.g. per keypoint, per individual) using xarray.apply_ufunc() with vectorize=True. The result is an int8 binary array (1 = changepoint, 0 = not) stored as ds["{target_feature}_{changepoint_name}"].

Parameters:

  • ds (xarray.Dataset) – Trial dataset containing target_feature.

  • target_feature (str) – Name of the variable to run detection on (e.g. "speed").

  • changepoint_name (str) – Suffix for the output variable name. The stored variable will be called "{target_feature}_{changepoint_name}" (e.g. "speed_troughs").

  • changepoint_func (callable) – A function f(x, **kwargs) -> array[int8] that takes a 1-D numpy array and returns a same-length binary indicator.

  • **func_kwargs – Forwarded to changepoint_func.

Returns:

The input dataset with the changepoint variable added in place.

Return type:

xarray.Dataset

Examples

>>> import ethograph as eto
>>> from ethograph.features.changepoints import find_troughs_binary
>>> dt = eto.open("experiment.nc")
>>> ds = dt.itrial(0)
>>> ds = eto.add_changepoints_to_ds(
...     ds,
...     target_feature="speed",
...     changepoint_name="troughs",
...     changepoint_func=find_troughs_binary,
...     prominence=0.3,
... )
>>> ds["speed_troughs"]
<xarray.DataArray 'speed_troughs' (time: 9000, keypoints: 7)>