mne_rt.tools.ASRDenoiser#

class mne_rt.tools.ASRDenoiser(cutoff: float = 5.0, max_dropout_fraction: float = 0.1, window_overlap: float = 0.5)[source]#

Bases: object

Artifact Subspace Reconstruction (ASR) for streaming EEG.

ASR [1][2] separates clean from artifactual activity by learning the statistics of a resting-state baseline and projecting out components that deviate beyond a threshold.

Calibration (fit())

Segment the baseline into overlapping windows of length \(T_{\mathrm{win}}\), compute the sample covariance per window, discard the fraction max_dropout_fraction with the highest total power (likely artifact), and eigendecompose the mean clean covariance:

\[\mathbf{C}_0 = \mathbf{U}\,\mathrm{diag}(d_1,\dots,d_p)\,\mathbf{U}^\top.\]

Per-component RMS thresholds are then set as:

\[T_k = \sigma \cdot \sqrt{d_k}, \qquad k = 1,\dots,p,\]

where \(\sigma\) = cutoff (default 5).

Cleaning (transform())

For each incoming window \(\mathbf{X} \in \mathbb{R}^{p \times n}\):

Project to calibration component space: \(\mathbf{Z} = \mathbf{U}^\top\mathbf{X}\).
Compute per-component RMS: \(r_k = \sqrt{\operatorname{mean}(Z_k^2)}\).
Zero components that exceed the threshold (\(r_k > T_k\)).
Back-project: \(\hat{\mathbf{X}} = \mathbf{U}\mathbf{Z}\).

Parameters:

cutofffloat, default 5.0: Rejection threshold in multiples of the clean-data per-component RMS. Lower values (3–4) are more aggressive; higher values (8–10) are more conservative. Mullen et al. (2015) recommend 5.
max_dropout_fractionfloat, default 0.1: Fraction of calibration windows with the highest total power to discard before estimating clean statistics. 0.1 retains the 90 % “cleanest” windows.
window_overlapfloat, default 0.5: Fractional overlap between consecutive calibration windows (0–1). 0.5 halves the effective hop size, doubling the number of windows.

Attributes:

cutofffloat
max_dropout_fractionfloat
window_overlapfloat

Raises:

ValueError: If constructor arguments are out of valid range.
RuntimeError: If transform() is called before fit().

See also

ant.tools.GEDAIDenoiser: GED-based spatial filter (requires forward model).
ant.tools.ORICA: Online recursive ICA for adaptive unmixing.
mne_rt.RTStream.fit_asr: Fit from a live session baseline.

References

Examples

>>> asr = ASRDenoiser(cutoff=5.0)
>>> asr.fit(baseline_data, sfreq=250.0)
>>> clean = asr.transform(noisy_window)

Added in version 1.0.0.

__init__(cutoff: float = 5.0, max_dropout_fraction: float = 0.1, window_overlap: float = 0.5) → None[source]#

Methods

`__init__`([cutoff, max_dropout_fraction, ...])
`fit`(data, sfreq[, window_len])	Calibrate from a clean resting-state baseline.
`transform`(data)	Remove artifact-dominated components from a data window.

Attributes

`eigenvectors`	Calibration eigenvectors \(\mathbf{U}\), shape (n_ch, n_ch).
`thresholds`	Per-component RMS thresholds, shape (n_channels,).

fit(data: ndarray, sfreq: float, window_len: float = 1.0) → ASRDenoiser[source]#

Calibrate from a clean resting-state baseline.

Parameters:

datandarray, shape (n_channels, n_samples): Baseline M/EEG recording. Eyes-closed resting state is recommended to minimise ocular and muscular contamination.
sfreqfloat: Sampling frequency in Hz.
window_lenfloat, default 1.0: Calibration window length in seconds. Shorter windows yield more estimates with higher variance; 0.5–1.0 s is typical.

Returns:

selfASRDenoiser

Raises:

ValueError: If fewer samples are available than one window, or all windows are discarded as outliers.

transform(data: ndarray) → ndarray[source]#

Remove artifact-dominated components from a data window.

Parameters:

datandarray, shape (n_channels, n_samples): Raw EEG window to clean.

Returns:

cleanndarray, shape (n_channels, n_samples): Cleaned data. Returned unchanged if no component exceeds its threshold (no-op when data is already clean).

Raises:

RuntimeError: If fit() has not been called.

property thresholds: ndarray#: Per-component RMS thresholds, shape (n_channels,).

property eigenvectors: ndarray#: Calibration eigenvectors \(\mathbf{U}\), shape (n_ch, n_ch).