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)

Artifact Subspace Reconstruction estimator.

ASR calibrates a clean signal subspace and reconstructs high-amplitude windows in continuous EEG or MEG data. It accepts channel-first NumPy arrays and supported MNE containers.

Parameters:

sfreqfloat or None, default=None

Sampling frequency in Hz. Required for NumPy input; inferred from MNE metadata when available.

cutofffloat, default=20.0

Threshold multiplier. Lower values generally reconstruct more components; the numerical interpretation depends on calibration and processing settings.

window_lengthfloat, default=0.5

Processing window length in seconds.

window_overlapfloat, default=0.66

Processing-window overlap fraction.

max_dropout_fractionfloat, default=0.1

Fraction of low-RMS values excluded from threshold estimation.

min_clean_fractionfloat, default=0.25

Minimum central fraction used for clean RMS statistics.

method{“standard”, “riemannian_windowed”, “riemannian”}, default=”standard”

Covariance/reconstruction backend. “riemannian” requires experimental=True.

experimentalbool, default=False

Required for the “riemannian” backend.

calibration{“auto”, “manual”}, default=”auto”

Whether to select clean calibration windows or use all supplied samples.

picksstr, list of str, list of int, or None, default=”eeg”

MNE channels to process. NumPy input uses all rows.

calibration_window_lengthfloat, default=1.0

Window length in seconds for automatic calibration selection.

calibration_window_overlapfloat, default=0.66

Overlap fraction for automatic calibration selection.

ref_max_bad_channelsfloat, default=0.075

Maximum bad-channel fraction in a calibration window.

ref_tolerancestuple of float, default=(-np.inf, 5.5)

Robust z-score bounds for calibration-window selection.

blocksizeint, default=10

Samples aggregated per calibration covariance block.

max_dimsfloat or int, default=0.66

Maximum fraction or number of dimensions reconstructed per window.

reject_by_annotationbool, default=True

Exclude bad annotated samples during Raw calibration and preserve them during Raw transformation.

skip_by_annotationtuple 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.

regularizationfloat, default=1e-8

Relative covariance eigenvalue floor.

filter_kind{“none”, “asr”, “highpass”}, default=”asr”

Filter used for statistics; reconstructed output uses the original data.

window_criterionfloat, int, or None, default=None

Optional final retained-sample criterion.

window_criterion_tolerancestuple of float, default=(-np.inf, 7.0)

Robust z-score bounds for the final criterion.

lookaheadfloat or None, default=None

Processing lookahead in seconds; None uses half a window.

stepsizeint or None, default=None

Samples between reconstruction updates; None uses half a window.

max_mem_mbint or None, default=512

Memory cap for covariance processing.

copybool, default=True

Reserved compatibility parameter; transformations return new outputs.

store_reconstruction_matricesbool, default=False

Store per-window reconstruction matrices in diagnostics.

random_stateint or None, default=None

Reserved for future stochastic calibration.

n_jobsint or None, default=None

Reserved for future parallel processing.

verbosebool, str, int, or None, default=None

Logging level.

See also

AdaptiveASR

Adaptive calibration variants for changing recording statistics.

JugglerASR

Alternative calibration-sample selection for high-motion recordings.

GuidedASR

Experimental guidance-aware reconstruction.

Notes

NumPy input uses (n_channels, n_times). MNE Raw and Epochs are supported; fit does not accept Evoked, while transform preserves the input container and metadata. Transformations do not mutate their input. Real applications should calibrate on representative clean data; the synthetic example only illustrates the estimator lifecycle [1][2][3].

References

[1]

Christian Andreas Edgar Kothe and Tzyy-Ping Jung. Artifact removal techniques with signal reconstruction. 2016. URL: https://patents.google.com/patent/US9474467B2/en.

[2]

Chi-Yuan Chang, Sheng-Hsiou Hsu, Luca Pion-Tonachini, and Tzyy-Ping Jung. Evaluation of artifact subspace reconstruction for automatic eeg artifact removal. In 2018 40th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC), 1242–1245. 2018. doi:10.1109/EMBC.2018.8512547.

[3]

Chi-Yuan Chang, Sheng-Hsiou Hsu, Luca Pion-Tonachini, and Tzyy-Ping Jung. Evaluation of artifact subspace reconstruction for automatic artifact components removal in multi-channel eeg recordings. IEEE Transactions on Biomedical Engineering, 67(4):1114–1121, 2020. doi:10.1109/TBME.2019.2930186.

Examples

>>> import numpy as np
>>> from mne_denoise.asr import ASR
>>> rng = np.random.default_rng(0)
>>> data = rng.standard_normal((8, 2000))
>>> asr = ASR(sfreq=250.0, cutoff=20.0)
>>> clean = asr.fit_transform(data)

fit(X: BaseRaw | BaseEpochs | np.ndarray, y=None, *, calibration: BaseRaw | BaseEpochs | np.ndarray | None = None, calibration_mask: np.ndarray | None = None, callback=None, verbose: bool | str | int | None = None) → ASR

Fit the ASR calibration state.

Parameters:

XRaw, Epochs, or ndarray

Data used for calibration when calibration is None. NumPy input is (n_channels, n_times).

yNone, default=None

Ignored for scikit-learn compatibility.

calibrationRaw, Epochs, or ndarray, default=None

Optional separate calibration data with matching channels.

calibration_maskndarray of bool, shape (n_times,), or None, default=None

Samples to use from a 2D calibration input.

callbackcallable or None, default=None

Synchronous calibration progress callback.

verbosebool, str, int, or None, default=None

Logging level for this call.

Returns:

ASR

The fitted estimator.

fit_transform(X: BaseRaw | BaseEpochs | np.ndarray, y=None, calibration: BaseRaw | BaseEpochs | np.ndarray | None = None, return_diagnostics: bool = False, *, callback=None, verbose: bool | str | int | None = None) → Any

Fit ASR and transform the input.

Parameters:

XRaw, Epochs, or ndarray

Data to clean and, when calibration is None, to calibrate on.

yNone, default=None

Ignored for scikit-learn compatibility.

calibrationRaw, Epochs, or ndarray, default=None

Optional separate calibration data.

return_diagnosticsbool, default=False

If true, return (cleaned, diagnostics).

callbackcallable or None, default=None

Callback passed to calibration and reconstruction.

verbosebool, str, int, or None, default=None

Logging level for this call.

Returns:

cleanedRaw, Epochs, or ndarray

Cleaned data with the input type and layout.

diagnosticsdict

Returned only when return_diagnostics=True.

get_calibration_mask() → ndarray

Return the boolean mask used for calibration.

Returns:

ndarray of bool

A copy of the clean-window or reference-sample mask.

get_diagnostics() → dict[str, Any]

Return diagnostics from the most recent transformation.

Returns:

dict

A copy of the latest diagnostics, or an empty dictionary before transform.

get_rejection_mask() → ndarray

Return the retained-sample mask from final window rejection.

Returns:

ndarray of bool, shape (n_times,)

True for samples retained by the optional window_criterion pass.

to_annotations(kind: str = 'repair', min_components: int = 1, description: str | None = None) → Any

Convert ASR decisions to MNE annotations.

Parameters:

kind{“repair”, “rejection”, “calibration”}, default=”repair”

Decision to annotate. “calibration” is available for JugglerASR reference-sample selection.

min_componentsint, default=1

Minimum reconstructed-component count for kind=”repair”.

descriptionstr or None, default=None

Annotation label; a kind-specific label is used when omitted.

Returns:

mne.Annotations

Annotation spans for the requested decision.

transform(X: BaseRaw | BaseEpochs | Evoked | np.ndarray, y=None, copy: bool | None = None, return_diagnostics: bool = False, *, callback=None, verbose: bool | str | int | None = None) → Any

Apply the fitted ASR model.

Parameters:

XRaw, Epochs, Evoked, or ndarray

Data to clean.

yNone, default=None

Ignored for scikit-learn compatibility.

copybool or None, default=None

Reserved compatibility parameter.

return_diagnosticsbool, default=False

If true, return (cleaned, diagnostics).

callbackcallable or None, default=None

Synchronous reconstruction progress callback.

verbosebool, str, int, or None, default=None

Logging level for this call.

Returns:

cleanedRaw, Epochs, Evoked, or ndarray

Cleaned data with the input type and layout.

diagnosticsdict

Returned only when return_diagnostics=True.