mne_denoise.asr.GuidedASR#

class mne_denoise.asr.GuidedASR(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, picks: str | list[str] | list[int] | None = 'eeg', calibration: str = 'auto', 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, artifact_biases: list | tuple | None = None, preserve_biases: list | tuple | None = None, reconstruction: str = 'soft', guidance_strength: float = 1.0, experimental: bool = False, random_state: int | None = None, n_jobs: int | None = None, verbose: bool | str | int | None = None)[source]#

DSS-biased soft Artifact Subspace Reconstruction (experimental).

Extends mne_denoise.asr.ASR (method="riemannian_windowed" backbone) with soft, structure-aware reconstruction. See the module docstring for the algorithm.

Parameters:

  • sfreq (float | None, default=None) – Sampling frequency in Hz. Required for NumPy input and inferred from MNE objects otherwise.

  • cutoff (float, default=20.0) – ASR threshold multiplier.

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

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

  • max_dropout_fraction (float, default=0.1) – Fraction of low-RMS values ignored during threshold estimation.

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

  • picks (str | list of str | list of int | None, default='eeg') – Channels processed for MNE inputs. None processes every channel.

  • calibration ({'auto', 'manual'}, default='auto') – Whether calibration selects clean windows or uses all samples.

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

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

  • ref_max_bad_channels (float, default=0.075) – Maximum bad-channel fraction in a clean calibration window.

  • ref_tolerances (tuple of float, default=(-inf, 5.5)) – Robust z-score limits for clean calibration windows.

  • blocksize (int, default=10) – Samples averaged into each robust covariance block.

  • max_dims (float | int, default=0.66) – Maximum number or fraction of reconstructed components per window.

  • reject_by_annotation (bool, default=True) – Exclude bad annotations during Raw calibration and preserve annotated samples during transform.

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

  • cov_estimator ({'geometric_median', 'mean', 'median'}, default='geometric_median') – Calibration covariance aggregation rule.

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

  • filter_kind ({'none', 'asr', 'highpass'}, default='none') – Filter used only for ASR statistics.

  • window_criterion (float | int | None, default=None) – Optional final retained-sample rejection criterion.

  • window_criterion_tolerances (tuple of float, default=(-inf, 7.0)) – Robust z-score limits for final window rejection.

  • lookahead (float | None, default=None) – Processing lookahead in seconds. None uses half a window.

  • stepsize (int | None, default=None) – Samples between reconstruction updates. None uses half a window.

  • max_mem_mb (int | None, default=512) – Bound selecting full-stack or rolling covariance updates.

  • copy (bool, default=True) – Reserved for API compatibility. Transform returns a new object.

  • store_reconstruction_matrices (bool, default=False) – Store every reconstruction matrix in processing diagnostics.

  • artifact_biases (sequence of DSS bias operators | None, default=None) – Operators (e.g. mne_denoise.dss.denoisers.LineNoiseBias, BandpassBias) whose biased covariance defines the artifact-like subspace C_artifact. Each must accept (n_channels, n_times) and return the same shape (the LinearDenoiser .apply contract). Multiple operators contribute equally after trace normalization.

  • preserve_biases (sequence of DSS bias operators | None, default=None) – Operators defining the brain-like subspace C_preserve to protect (e.g. PeakFilterBias for SSVEP, BandpassBias for a target band). Multiple operators contribute equally after trace normalization.

  • reconstruction ({'soft', 'hard'}, default='soft') – 'soft' uses continuous weights only for ASR-flagged components; 'hard' reproduces standard ASR’s binary keep/reject.

  • guidance_strength (float, default=1.0) – Guidance contribution in [0, 1]. Zero gives baseline soft-ASR weights and one applies the full artifact/preserve adjustment.

  • experimental (bool, default=False) – Must be True to use the guided soft reconstruction.

  • 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 ASR progress logging.

See also

ASR

Standard Artifact Subspace Reconstruction estimator.

process_guided_asr

Low-level guided processing function.

Notes

GuidedASR soft reconstruction is an unpublished, unvalidated research prototype. Its current evidence is limited to unit tests and synthetic benchmarks. It must not be treated as a validated EEG preprocessing method without independent checks on the target data and scientific endpoints.

With reconstruction="hard" and no bias operators, GuidedASR is identical to ASR(method="riemannian_windowed").

Equal bias weighting, the isotropic evidence reference, and the linear guidance equation are explicit experimental modeling choices.

Examples

Create an explicitly opted-in estimator:

>>> from mne_denoise.asr import GuidedASR
>>> guided = GuidedASR(sfreq=250.0, experimental=True)
__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, picks: str | list[str] | list[int] | None = 'eeg', calibration: str = 'auto', 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, artifact_biases: list | tuple | None = None, preserve_biases: list | tuple | None = None, reconstruction: str = 'soft', guidance_strength: float = 1.0, experimental: 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])

Calibrate ASR and fit the optional guidance covariances.

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.