cogpy.triggered

Triggered analysis primitives for event-locked epochs: triggered averages, template estimation, scaling, and template subtraction.

How-to: How to do triggered analysis

Submodules

cogpy.triggered.stats

Triggered statistics on event-locked epochs.

cogpy.triggered.template

Template estimation, fitting, and subtraction primitives.

Triggered analysis primitives for event-locked epochs.

Statistics: triggered_average, triggered_std, triggered_median, triggered_snr. Template ops: estimate_template, fit_scaling, subtract_template.

Consumes epoch arrays (e.g. from cogpy.brainstates.intervals.perievent_epochs) and returns summary statistics, templates, or cleaned signals.

cogpy.triggered.estimate_template(epochs, *, method='mean', event_dim='event')

Estimate a template waveform from stacked epochs.

Parameters:

  • epochs (xr.DataArray or ndarray) – Epoch array with shape (n_events, ..., n_lag).

  • method ({"mean", "median", "trimmean"}) –

    Aggregation method.

    • "mean": arithmetic mean (default).

    • "median": robust to outliers.

    • "trimmean": 20% trimmed mean (requires scipy).

  • event_dim (str) – Name of event dimension (xarray only).

Returns:

Template with shape (..., n_lag) — one fewer axis than input.

Return type:

xr.DataArray or ndarray

See also

subtract_template

Subtract estimated template from continuous signal.

cogpy.brainstates.intervals.perievent_epochs

Extract signal epochs time-locked to events.

Examples

>>> import numpy as np
>>> epochs = np.random.randn(50, 100)  # 50 events, 100 time-lag samples
>>> tmpl = estimate_template(epochs, method="mean")
>>> tmpl.shape
(100,)
cogpy.triggered.fit_scaling(epochs, template)

Fit per-event scaling coefficients via least-squares projection.

For each event i, finds scalar alpha_i minimizing ||epochs[i] - alpha_i * template||^2.

Parameters:

  • epochs ((n_events, ..., n_lag) float) – Epoch array.

  • template ((..., n_lag) float) – Template waveform (same shape as a single epoch).

Returns:

alpha – Per-event scaling coefficients.

Return type:

(n_events,) float

Notes

This is the standard dot-product projection: alpha_i = <epochs_i, template> / <template, template>.

cogpy.triggered.subtract_template(signal, event_samples, template, *, scaling=None)

Subtract a template waveform at each event location in a continuous signal.

Parameters:

  • signal ((n_channels, n_time) or (n_time,) float) – Continuous signal. If xr.DataArray, operates on .values and returns an xr.DataArray with same metadata.

  • event_samples ((n_events,) int) – Sample indices where template onset aligns.

  • template ((n_channels, n_lag) or (n_lag,) float) – Template to subtract. Must be broadcastable with the channel dimension of signal.

  • scaling ((n_events,) float, optional) – Per-event amplitude scaling. If None, uses 1.0 for all events.

Returns:

cleaned – Signal with template subtracted at each event.

Return type:

same type and shape as signal

See also

estimate_template

Estimate a template waveform from stacked epochs.

cogpy.brainstates.intervals.perievent_epochs

Extract signal epochs time-locked to events.

Notes

Out-of-bounds events (where template would extend beyond signal boundaries) are silently skipped.

cogpy.triggered.triggered_average(epochs, *, event_dim='event')

Mean across events (event-triggered average / ETA).

Parameters:

  • epochs (xr.DataArray or ndarray) – Epoch array with an event axis. If ndarray, the first axis is assumed to be events.

  • event_dim (str) – Name of event dimension (xarray only, default "event").

Returns:

Mean across events, preserving all other dimensions.

Return type:

xr.DataArray or ndarray

cogpy.triggered.triggered_median(epochs, *, event_dim='event')

Median across events (robust alternative to mean).

Parameters:

  • epochs (xr.DataArray or ndarray) – Epoch array with event axis.

  • event_dim (str) – Name of event dimension (xarray only).

Returns:

Median across events.

Return type:

xr.DataArray or ndarray

cogpy.triggered.triggered_snr(epochs, *, event_dim='event')

Signal-to-noise ratio of the triggered average.

Defined as mean / (std / sqrt(n_events)), i.e. the ratio of the average to its standard error. High values indicate a consistent event-locked component.

Parameters:

  • epochs (xr.DataArray or ndarray) – Epoch array with event axis.

  • event_dim (str) – Name of event dimension (xarray only).

Returns:

SNR array, same shape as a single epoch.

Return type:

xr.DataArray or ndarray

cogpy.triggered.triggered_std(epochs, *, event_dim='event', ddof=1)

Standard deviation across events.

Parameters:

  • epochs (xr.DataArray or ndarray) – Epoch array with event axis.

  • event_dim (str) – Name of event dimension (xarray only).

  • ddof (int) – Delta degrees of freedom (default 1 = unbiased).

Returns:

Std across events, preserving all other dimensions.

Return type:

xr.DataArray or ndarray