epoch#

Event-triggered epoching / averaging on the shared master clock.

Once trial onsets are available on the camera timeline (see mesofield.datakit.sources.behavior.mouseportal.MousePortalTrials), an event-triggered average is just: window each timeseries around every onset onto a common peri-event grid and average across events.

Works for any time-indexed signal whose first axis is time: a scalar ROI/dF-F trace (T,), a multi-region trace (T, R), or a widefield image stack (T, H, W).

Example#

>>> from mesofield.datakit import load_dataset
>>> from mesofield.datakit.epoch import event_triggered_average
>>> ds = load_dataset("data")
>>> trials = ds.select(source="mouseportal_trials")      # interval table
>>> meso   = ds.select(source="meso_mean")               # (t, trace)
>>> onsets = trials.value.query("phase == 'trial'")["start_s"].to_numpy()
>>> grid, eta, stack = event_triggered_average(meso.t, meso.value, onsets,
...                                             pre=1.0, post=3.0, fs=10.0,
...                                             baseline=(-1.0, 0.0))
>>> eta.shape            # (len(grid), *feature_shape)
mesofield.datakit.epoch.peri_event_grid(pre, post, fs)[source]#

Uniform peri-event time grid in seconds: [-pre, post) at fs Hz.

Parameters:
Return type:

ndarray

mesofield.datakit.epoch.epoch(t, values, onsets, *, pre, post, fs, method='interp')[source]#

Cut a peri-event stack around each onset.

Parameters#

t : (T,) array of sample times in seconds (master clock; strictly increasing). values : (T, …) array; first axis aligns with t. onsets : event times in seconds (same clock as t). pre, post : window seconds before/after each onset. fs : sampling rate of the returned uniform grid. method : “interp” (linear, good for traces) or “nearest” (frame indexing,

cheap for image stacks).

Returns#

grid : (n_bins,) peri-event times. stack : (n_onsets, n_bins, *feature_shape); out-of-range samples are NaN

(“interp”) or dropped via NaN fill.

Parameters:
Return type:

Tuple[ndarray, ndarray]

mesofield.datakit.epoch.event_triggered_average(t, values, onsets, *, pre, post, fs, baseline=None, method='interp')[source]#

Event-triggered average + the underlying per-event stack.

baseline=(b0, b1) subtracts each event’s mean over that peri-event window (seconds, relative to onset) before averaging.

Returns (grid, eta, stack) where eta is the nan-mean across events with shape (n_bins, *feature_shape).

Parameters:
Return type:

Tuple[ndarray, ndarray, ndarray]