mne_denoise.asr.ASR#

class mne_denoise.asr.ASR(sfreq: float | None = None, cutoff: float = 20.0, window_length: float = 0.5, window_overlap: float = 0.66, max_dropout_fraction: float = 0.1, min_clean_fraction: float = 0.25, method: str = 'standard', experimental: bool = False, calibration: str = 'auto', picks: str | list[str] | list[int] | None = 'eeg', calibration_window_length: float = 1.0, calibration_window_overlap: float = 0.66, ref_max_bad_channels: float = 0.075, ref_tolerances: tuple[float, float] = (-inf, 5.5), blocksize: int = 10, max_dims: float | int = 0.66, reject_by_annotation: bool = True, skip_by_annotation: tuple[str, ...] = ('bad', 'bad_acq_skip'), cov_estimator: str = 'geometric_median', regularization: float = 1e-08, filter_kind: str = 'asr', window_criterion: float | int | None = None, window_criterion_tolerances: tuple[float, float] = (-inf, 7.0), lookahead: float | None = None, stepsize: int | None = None, max_mem_mb: int | None = 512, copy: bool = True, store_reconstruction_matrices: bool = False, random_state: int | None = None, n_jobs: int | None = None, verbose: bool | str | int | None = None)[source]#

Artifact Subspace Reconstruction (ASR) scikit-learn transformer.

ASR is an automated, statistical method for removing high-amplitude, transient artifacts (such as eye blinks, muscle bursts, and sensor motion) from continuous electroencephalography (EEG) or magnetoencephalography (MEG) data.

It operates by learning a clean signal subspace from a calibration dataset (or clean segments of the target dataset) and using this baseline to identify and reconstruct corrupted segments. This class provides a fully scikit-learn and MNE-compatible interface.

Parameters:

  • sfreq (float | None, default=None) – Sampling frequency in Hz. Required for NumPy arrays. For MNE objects, this may be None and is inferred from info['sfreq'].

  • cutoff (float, default=20.0) – ASR threshold multiplier. Values around 20 are conservative; lower values clean more aggressively.

  • window_length (float, default=0.5) – Processing/statistics window length in seconds.

  • window_overlap (float, default=0.66) – Overlap fraction for processing and threshold-fitting windows.

  • max_dropout_fraction (float, default=0.1) – Fraction of lowest RMS values ignored while estimating thresholds.

  • min_clean_fraction (float, default=0.25) – Minimum central fraction used to estimate clean RMS statistics.

  • method ({'standard', 'riemannian', 'riemannian_windowed'}, default='standard') –

    ASR backend.

    • 'standard' — standard Euclidean ASR.

    • 'riemannian' — experimental SPD-manifold covariance backend, NOTE: this backend computes one covariance + one reconstruction matrix for the entire stream, so its cleaned output is cutoff-invariant on real EEG (the cutoff knob does not meaningfully change the result). Use it primarily for research or benchmarking, not for cutoff tuning.

    • 'riemannian_windowed' — per-window Riemannian backend that keeps the Riemannian-aggregated (geometric-median) calibration but applies a standard per-window eigendecomposition at processing time. Unlike 'riemannian', its cutoff knob works: % data modified and % variance reduced scale monotonically with cutoff like 'standard' does. This is a first-class backend (no experimental flag required): its processing is numerically identical to standard ASR while preserving robust manifold calibration. Prefer it over 'riemannian' whenever you need cutoff control with Riemannian-robust calibration.

  • experimental (bool, default=False) – Explicit opt-in for the unstable method='riemannian' research backend (cutoff-invariant on real EEG). Not required for 'riemannian_windowed'.

  • calibration ({'auto', 'manual'}, default='auto') – Calibration mode. 'auto' selects clean windows before fitting; 'manual' uses all supplied calibration samples.

  • calibration_window_length (float, default=0.5) – Window length in seconds for automatic clean-window selection.

  • calibration_window_overlap (float, default=0.66) – Overlap fraction for automatic clean-window selection.

  • ref_max_bad_channels (float, default=0.2) – Maximum fraction of channels exceeding robust tolerances in a clean calibration window.

  • ref_tolerances (tuple of float, default=(-3.5, 5.0)) – Lower and upper robust z-score bounds for clean-window selection.

  • blocksize (int, default=10) – Number of successive samples averaged into each covariance block for robust calibration covariance estimation.

  • max_dims (float | int, default=0.66) – Maximum number of dimensions reconstructed per processing window.

  • reject_by_annotation (bool, default=True) – If True, samples under bad annotations are excluded during Raw calibration and preserved during Raw transform.

  • skip_by_annotation (tuple of str, default=('bad', 'bad_acq_skip')) – Annotation description prefixes treated as bad when reject_by_annotation=True.

  • cov_estimator ({'geometric_median', 'mean', 'median'}, default='geometric_median') – Aggregation rule for calibration-window covariance matrices.

  • regularization (float, default=1e-8) – Relative eigenvalue floor for covariance regularization.

  • filter_kind ({'none', 'asr', 'highpass'}, default='asr') – Statistics-only filter. The cleaned output is reconstructed from the original unfiltered data. Set 'none' to disable spectral shaping.

  • window_criterion (float | int | None, default=None) – Optional clean_windows-style final rejection criterion. If numeric, this is the maximum tolerated number or fraction of bad channels per retained window after ASR correction. None disables final rejection-mask computation.

  • window_criterion_tolerances (tuple of float, default=(-3.5, 5.0)) – Lower and upper robust z-score thresholds for final clean_windows-style retained-sample masking.

  • lookahead (float | None, default=None) – Processing lookahead in seconds. Defaults to window_length / 2.

  • stepsize (int | None, default=None) – Number of samples between reconstruction-matrix updates. If None, use the default floor(sfreq * window_length / 2).

  • max_mem_mb (int | None, default=200) – Reserved memory limit for future chunking.

  • copy (bool, default=True) – Reserved API flag. Transform returns a new object/array.

  • store_reconstruction_matrices (bool, default=False) – Store per-window reconstruction matrices in diagnostics.

  • random_state (int | None, default=None) – Reserved for future stochastic calibration strategies.

  • n_jobs (int | None, default=None) – Reserved for future parallel processing.

  • verbose (bool | str | int | None, default=None) – Controls progress logging on the mne_denoise.asr logger. True enables INFO messages (e.g. the calibration summary), False restricts to warnings, a level name/int sets that level, and None leaves the current logging configuration unchanged.

Notes

Key Tuning Parameters

  • cutoff: The primary dial for ASR aggressiveness. Its numerical scale depends on the calibration rule, statistics filter, reconstruction implementation, and data regime. The default of 20 supports legacy and reference-implementation comparisons; it is not a universally validated conservative operating point. Freeze and validate the value for each intended regime.

  • method: Use 'standard' for standard ASR workflows, or 'riemannian_windowed' for a more mathematically robust manifold-based calibration covariance estimation that still responds monotonically to cutoff.

  • window_criterion: Provide a numeric value (e.g., 0.25) to enable an statistical final rejection pass after ASR reconstruction, which drops any remaining windows that still contain too many artifactual channels.

Calibration vs. Reconstruction Windows

ASR uses two different sliding windows. calibration_window_length (default 1.0s) is used exclusively during fit() to find clean baseline segments. window_length (default 0.5s) is used during transform() to detect and reconstruct artifacts.

sfreq_#

Sampling frequency used during fitting.

Type:

float

ch_names_#

Fitted channel names for MNE inputs.

Type:

list of str | None

picks_#

Row/channel indices cleaned in the fitted data.

Type:

ndarray

M_#

Calibration covariance square root.

Type:

ndarray

T_#

Direction-dependent threshold matrix.

Type:

ndarray

thresholds_#

Per-component RMS thresholds.

Type:

ndarray

clean_window_mask_#

Calibration windows retained as clean.

Type:

ndarray

sample_mask_#

Samples reconstructed during the last transform.

Type:

ndarray

rejection_sample_mask_#

Boolean retained-sample mask from optional clean_windows-style final rejection. Present after transforms when window_criterion is enabled.

Type:

ndarray

n_components_reconstructed_#

Number of reconstructed components per processing window.

Type:

ndarray

diagnostics_#

Last-transform diagnostics.

Type:

dict

calibration_info_#

Calibration diagnostics.

Type:

dict

Examples

Clean an MNE Raw object using standard ASR:

>>> import mne
>>> from mne_denoise.asr import ASR
>>> raw = mne.io.read_raw_fif("sample_audvis_raw.fif", preload=True)
>>> asr = ASR(cutoff=20.0)
>>> # Calibration and reconstruction happen in one pass with fit_transform
>>> clean_raw = asr.fit_transform(raw)

Clean a NumPy array, passing the sampling frequency explicitly:

>>> import numpy as np
>>> data = np.random.randn(32, 5000)
>>> asr = ASR(sfreq=250.0, cutoff=15.0)
>>> clean_data = asr.fit_transform(data)

Perform independent calibration on a known clean baseline:

>>> asr = ASR(cutoff=20.0)
>>> asr.fit(clean_baseline_raw)
>>> clean_target_raw = asr.transform(target_raw)
__init__(sfreq: float | None = None, cutoff: float = 20.0, window_length: float = 0.5, window_overlap: float = 0.66, max_dropout_fraction: float = 0.1, min_clean_fraction: float = 0.25, method: str = 'standard', experimental: bool = False, calibration: str = 'auto', picks: str | list[str] | list[int] | None = 'eeg', calibration_window_length: float = 1.0, calibration_window_overlap: float = 0.66, ref_max_bad_channels: float = 0.075, ref_tolerances: tuple[float, float] = (-inf, 5.5), blocksize: int = 10, max_dims: float | int = 0.66, reject_by_annotation: bool = True, skip_by_annotation: tuple[str, ...] = ('bad', 'bad_acq_skip'), cov_estimator: str = 'geometric_median', regularization: float = 1e-08, filter_kind: str = 'asr', window_criterion: float | int | None = None, window_criterion_tolerances: tuple[float, float] = (-inf, 7.0), lookahead: float | None = None, stepsize: int | None = None, max_mem_mb: int | None = 512, copy: bool = True, store_reconstruction_matrices: bool = False, random_state: int | None = None, n_jobs: int | None = None, verbose: bool | str | int | None = None) → None[source]#

Methods

__init__([sfreq, cutoff, window_length, ...])

fit(X[, y, calibration, calibration_mask])

Fit ASR calibration state.

fit_transform(X[, y, calibration, ...])

Fit ASR and apply it to X.

get_calibration_mask()

Return the boolean mask of data used for calibration.

get_diagnostics()

Return diagnostics from the last transform.

get_metadata_routing()

Get metadata routing of this object.

get_params([deep])

Get parameters for this estimator.

get_rejection_mask()

Return the retained-sample mask from final clean_windows-style rejection.

set_fit_request(*[, calibration, ...])

Configure whether metadata should be requested to be passed to the fit method.

set_output(*[, transform])

Set output container.

set_params(**params)

Set the parameters of this estimator.

set_transform_request(*[, copy, ...])

Configure whether metadata should be requested to be passed to the transform method.

to_annotations([kind, min_components, ...])

Convert ASR decisions into MNE annotations.

transform(X[, y, copy, return_diagnostics])

Apply the fitted ASR model.