Dataset

Dataset-level builders and augmenters that operate on an xarray.Dataset or TrialTree. Use these to build a basic tree from a single long recording, downsample, or attach changepoint / colour features.

For the pynapple equivalents (load_nap_data, add_changepoints_to_nap, …) see Pynapple IO.

---

Resampling

ethograph.io.dataset.downsample_trialtree(dt, factor)

Downsample every trial in a TrialTree using a min-max envelope.

For each contiguous block of factor samples, two values are kept: the block minimum and maximum. This preserves peaks and troughs (important for spike-like signals) while reducing the number of samples by roughly factor / 2.

All time-like dimensions in every trial are downsampled independently, so datasets with mixed sampling rates (e.g. 30 Hz pose + 44 kHz audio) are handled correctly.

Parameters:

• dt (TrialTree) – Input tree. Not modified in place.

• factor (int) – Number of raw samples per envelope block. For example, factor=10 on a 30 Hz signal produces ~6 Hz output (2 points per block).

Returns:

New tree with downsampled data. Each trial’s attrs includes downsample_factor and downsample_method.

Return type:

TrialTree

Examples

>>> import ethograph as eto
>>> dt = eto.open("high_rate_experiment.nc")
>>> dt_small = eto.downsample_trialtree(dt, factor=20)
>>> dt_small.save("experiment_downsampled.nc")

---

Building

ethograph.io.dataset.add_changepoints_to_ds(ds, target_feature, changepoint_name, changepoint_func, **func_kwargs)

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)>

ethograph.io.dataset.add_angle_rgb_to_ds(ds, smoothing_params)

Compute heading angles and RGB color-coding from 2-D position data.

For each individual/keypoint combination, calculates the heading angle from consecutive (x, y) positions and maps it to an RGB color via get_angle_rgb(). Gaussian smoothing is applied before angle computation.

Adds two variables to ds:

• angles – heading angle in radians.

• angle_rgb – (R, G, B) triplet per time-step

Parameters:

• ds (xarray.Dataset) – Dataset containing a position variable with at least space=["x", "y"] and a time dimension.

• smoothing_params (dict) – Keyword arguments forwarded to scipy.ndimage.gaussian_filter1d() (e.g. {"sigma": 3}).

Returns:

The input dataset with angles and angle_rgb added in-place.

Return type:

xarray.Dataset