aind_ephys_utils.ops.align module

Alignment operations.

This module contains the core implementation for aligning spikes/continuous signals to event times.

The public entry point is align, which is used by the .ephys.align accessor.

exception aind_ephys_utils.ops.align.EphysAlignError

Bases: ValueError

Raised when alignment inputs are invalid or unsupported.

aind_ephys_utils.ops.align.align(data: DataArray | ndarray | Sequence[object] | Sequence[Sequence[object]], *, events: DataArray | Sequence[float] | ndarray, window: Tuple[float, float], to: str | None = None, dims: Sequence[str] | None = None, coords: Dict[str, object] | None = None, return_type: str = 'auto') → DataArray | object

Align data to an event and extract a time window around it.

Parameters:

  • data – Input data. Supports xarray.DataArray (dense or ragged spikes), dense NumPy arrays, and ragged spike lists.

  • events – Event times used for alignment. Can be an xarray.DataArray with an event coordinate, or array-like event times.

  • window – Alignment window (tmin, tmax) relative to each event.

  • to – Event label to align to when events is xarray-backed.

  • dims – Optional dimension names used when data is a dense NumPy array. Required for dense NumPy input.

  • coords – Optional coordinate mapping used when converting dense NumPy input to xarray.DataArray.

  • return_type – Output type policy: "auto", "xarray", or "numpy". "auto" returns xarray for xarray input and NumPy/list output for NumPy or ragged-list input.

Returns:

Aligned output restricted to window. Continuous/binned input returns dense aligned data with shifted time. Ragged session spikes return trialized ragged spikes.

Return type:

xr.DataArray or object

Notes

to is optional for array-like/ndarray events inputs. For xarray events objects, to is required to select an event label.