Pynapple IO#

Loaders and augmenters for pynapple-backed data (NWB files and .npz pynapple folders). These are the pynapple counterparts of the xarray builders in Dataset.

Loading#

ethograph.io.pynapple.load_nap_data(path)[source]#

Load pynapple data from a file or folder.

Supports .nwb, .npz, or a directory (pynapple folder). When loading a single .npz, sibling files in the same directory are also loaded (e.g. trials.npz alongside speed.npz).

Return type:

tuple[dict, nap.IntervalSet | None]

Returns:

  • data (dict) – Loaded pynapple objects keyed by name.

  • trials_ep (IntervalSet or None) – Trial intervals if found in the data.

Building#

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']