mne_denoise.dss.denoisers.CycleAverageBias

class mne_denoise.dss.denoisers.CycleAverageBias(event_samples: Sequence[int] | Sequence[tuple[int, int]], window: tuple[int | float, int | float] = (-100, 200), *, window_unit: Literal['samples', 'seconds'] = 'samples', sfreq: float | None = None, event_origin: Literal['data', 'raw'] = 'data', first_samp: int | None = None, min_events: int = 2)

Fixed-window event-locked averaging bias.

The operation estimates one average window from the supplied events and places that average at every event. Samples outside event windows are zero. When windows overlap, their contributions are averaged, so the result is independent of event order. Duplicate coordinates are removed before the average is estimated.

This is a useful fixed-window extension for stereotyped events such as ECG QRS complexes or blinks. It is not the complete quasiperiodic method of Särelä and Valpola (2005): that method estimates variable peak-to-peak periods, warps them to a common duration, and iteratively updates QRS events in its cardiac application.

Parameters:

• event_samples (array-like of int, shape (n_events,) or (n_events, 2)) – Event coordinates. One-dimensional coordinates apply only to 2-D data and use event_origin. For 3-D channel-first data, coordinates must be (epoch_index, sample_index) pairs; both values are zero-based and relative to the supplied epoched array. Flat global sample indices are rejected for 3-D data.

• window (tuple of int or float) – Half-open interval [event + start, event + stop). The resolved interval must be complete for every event; boundary-crossing and out-of-range coordinates raise an error rather than being discarded.

• window_unit ({"samples", "seconds"}, default="samples") – Unit of window. Sample boundaries must be integers. Second-valued boundaries are converted using nearest-sample rounding (ties to even).

• sfreq (float | None, default=None) – Sampling frequency in Hz. Required for window_unit="seconds".

• event_origin ({"data", "raw"}, default="data") – Origin of one-dimensional event coordinates. "data" means sample zero is the first sample passed to apply(). "raw" means MNE acquisition sample numbering and requires first_samp. Per-epoch coordinates always use the data-relative origin.

• first_samp (int | None, default=None) – First acquisition sample of the corresponding MNE Raw object. It is subtracted exactly once when event_origin="raw" and is otherwise forbidden.

• min_events (int, default=2) – Minimum number of unique, complete events. Values below two are not allowed because one window has no across-event repeatability contrast. Two is a mathematical minimum, not a practical recommendation; stable cardiac estimates will generally require many representative beats.

Notes

Public input is converted to float32 or float64 before averaging. Integer and other real numerical dtypes produce float64 output. Input arrays are never modified.

Examples

MNE event arrays use acquisition sample numbering:

>>> from mne.preprocessing import find_ecg_events
>>> from mne_denoise.dss.denoisers import CycleAverageBias
>>> ecg_events, _, _ = find_ecg_events(raw)
>>> bias = CycleAverageBias(
...     event_samples=ecg_events[:, 0],
...     window=(-0.2, 0.4),
...     window_unit="seconds",
...     sfreq=raw.info["sfreq"],
...     event_origin="raw",
...     first_samp=raw.first_samp,
... )
>>> biased_data = bias.apply(raw.get_data())

References

Särelä, J., & Valpola, H. (2005). Denoising source separation. Journal of Machine Learning Research, 6, 233-272.

__init__(event_samples: Sequence[int] | Sequence[tuple[int, int]], window: tuple[int | float, int | float] = (-100, 200), *, window_unit: Literal['samples', 'seconds'] = 'samples', sfreq: float | None = None, event_origin: Literal['data', 'raw'] = 'data', first_samp: int | None = None, min_events: int = 2) → None

Methods

__init__(event_samples[, window, ...])
apply(data)	Apply fixed-window event-locked averaging.