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)[source]#

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)[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, keypoint: 7)>
ethograph.io.dataset.add_angle_rgb_to_ds(ds, smoothing_params)[source]#

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

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

Return type:

xarray.Dataset

Pynapple equivalents#

ethograph.io.pynapple.add_changepoints_to_nap(data, target_feature, changepoint_func, **func_kwargs)[source]#

Detect changepoints in a pynapple time series and return them as a TsGroup.

Applies changepoint_func independently to each unit or column in data. Returns a nap.TsGroup where each unit contains the changepoint timestamps for one source series. Source metadata (label, feature name, type) is stored as group metadata columns; if data is itself a TsGroup, its metadata columns are forwarded as well.

Parameters:

  • data (nap.Tsd | nap.TsdFrame | nap.TsGroup) – Input time series. For a Tsd a single unit is produced; for a TsdFrame one unit per column; for a TsGroup one unit per neuron/unit.

  • target_feature (str) – Human-readable label recorded in the output metadata (e.g. "speed").

  • changepoint_func (callable) – A function f(x, **kwargs) -> array that accepts a 1-D numpy array of values and returns an array of changepoint times (or a binary indicator of the same length).

  • **func_kwargs – Forwarded to changepoint_func.

Returns:

One unit per input series, containing changepoint timestamps.

Return type:

nap.TsGroup

Examples

>>> import ethograph as eto
>>> from ethograph.features.changepoints import find_troughs
>>> data = eto.load_nap_data("experiment.nwb")
>>> cp_group = eto.add_changepoints_to_nap(
...     data["speed"],
...     target_feature="speed",
...     changepoint_func=find_troughs,
...     prominence=0.3,
... )
ethograph.io.pynapple.add_angle_rgb_to_nap(tsdframe, smoothing_params, position_key='position', xy_columns=['x', 'y'])[source]#

Compute heading-angle RGB colour coding from 2-D position data.

Calculates the heading angle from consecutive (x, y) positions in tsdframe and maps each angle to an RGB triplet via get_angle_rgb(). Gaussian smoothing is applied before angle computation.

Parameters:

  • tsdframe (nap.TsdFrame) – Position data with at least two columns (x and y). If more than two columns are present, xy_columns selects which two to use.

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

  • position_key (str, optional) – Input type passed to get_angle_rgb (default "position").

  • xy_columns (list[str], optional) – Column names to use as x and y when tsdframe has more than two columns (default ["x", "y"]).

Returns:

A new TsdFrame with three columns ["R", "G", "B"] on the same time support as tsdframe.

Return type:

nap.TsdFrame

Examples

>>> import ethograph as eto
>>> data = eto.load_nap_data("experiment.nwb")
>>> rgb = eto.add_angle_rgb_to_nap(
...     data["position"],
...     smoothing_params={"sigma": 3},
... )
>>> rgb.columns
['R', 'G', 'B']