mne_denoise.asr.AdaptiveASR#

class mne_denoise.asr.AdaptiveASR(sfreq: float | None = None, cutoff: float = 20.0, variant: str = 'psw', window_length: float = 0.5, update_window_length: float = 0.1, calibration_window_length: float = 1.0, calibration_window_overlap: float = 0.66, ref_max_bad_channels: float = 0.2, ref_tolerances: tuple[float, float] = (-3.5, 5.0), blocksize: int = 10, max_dims: float | int = 0.66, max_dropout_fraction: float = 0.1, min_clean_fraction: float = 0.25, picks: str | list[str] | list[int] | None = 'eeg', reject_by_annotation: bool = True, skip_by_annotation: tuple[str, ...] = ('bad', 'bad_acq_skip'), regularization: float = 1e-08, window_criterion: float | int | str | 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, learning_rate: float = 0.2, tau: float | None = None, mw_window_length: float = 20.0, mw_mode: str = 'final_state', random_state: int | None = None, n_jobs: int | None = None, verbose: bool | str | int | None = None)[source]#

Adaptive Artifact Subspace Reconstruction estimator.

AdaptiveASR extends ASR with principal-subspace or moving-window calibration updates. It accepts channel-first NumPy arrays and supported MNE containers.

Parameters:

sfreqfloat or None, default=None: Sampling frequency in Hz; inferred from MNE metadata when available.
cutofffloat, default=20.0: ASR threshold multiplier. Lower values generally reconstruct more components.
variant{“psw”, “psp”, “mw”}, default=”psw”: Adaptive update rule.
window_lengthfloat, default=0.5: Processing window length in seconds.
update_window_lengthfloat, default=0.1: RMS-statistics window length within an adaptive update.
calibration_window_lengthfloat, default=1.0: Automatic calibration-window length in seconds.
calibration_window_overlapfloat, default=0.66: Automatic calibration-window overlap.
ref_max_bad_channelsfloat, default=0.2: Maximum bad-channel fraction for calibration windows.
ref_tolerancestuple of float, default=(-3.5, 5.0): Robust z-score bounds for calibration-window selection.
blocksizeint, default=10: Samples per calibration covariance block.
max_dimsfloat or int, default=0.66: Maximum fraction or number of reconstructed dimensions.
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.
picksstr, list of str, list of int, or None, default=”eeg”: MNE channels to process; NumPy input uses all rows.
reject_by_annotationbool, default=True: Exclude bad annotated samples during calibration.
skip_by_annotationtuple of str, default=(“bad”, “bad_acq_skip”): Annotation prefixes treated as bad.
regularizationfloat, default=1e-8: Relative covariance eigenvalue floor.
window_criterionfloat, int, str, 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.
stepsizeint or None, default=None: Samples between reconstruction updates.
max_mem_mbint or None, default=512: Memory bound for internal chunking.
copybool, default=True: Reserved compatibility parameter; transformations return new outputs.
store_reconstruction_matricesbool, default=False: Store per-window reconstruction matrices in diagnostics.
learning_ratefloat, default=0.2: Adaptive feed-forward update step.
taufloat or None, default=None: Lateral-update time constant; derived from learning_rate when omitted.
mw_window_lengthfloat, default=20.0: Moving-window length in seconds for variant=”mw”.
mw_mode{“final_state”, “sliding”}, default=”final_state”: Moving-window mode. “final_state” fits the stream and uses the final state; “sliding” calibrates and cleans each moving window in fit_transform.
random_stateint or None, default=None: Reserved for stochastic internal steps.
n_jobsint or None, default=None: Reserved for future parallel processing.
verbosebool, str, int, or None, default=None: Logging level.

See also

ASR: Standard fixed-calibration Artifact Subspace Reconstruction.
JugglerASR: Alternative calibration selection without adaptive state updates.

Notes

partial_fit updates the adaptive calibration state for variant=”psp” or variant=”psw”; variant=”mw” does not support partial_fit. NumPy input uses (n_channels, n_times) or (n_epochs, n_channels, n_times). Transform preserves the input MNE container and does not mutate it [1][2].

References

Examples

>>> import numpy as np
>>> from mne_denoise.asr import AdaptiveASR
>>> rng = np.random.default_rng(0)
>>> data = rng.standard_normal((8, 8000))
>>> model = AdaptiveASR(sfreq=250.0, variant="psw")
>>> _ = model.fit(data[:, :4000])
>>> _ = model.partial_fit(data[:, 4000:])
>>> clean = model.transform(data)

Fit the initial adaptive ASR state.

Parameters:

XRaw, Epochs, or ndarray: Data used for initial calibration.
yNone, default=None: Ignored for scikit-learn compatibility.
calibrationRaw, Epochs, or ndarray, default=None: Optional separate calibration data.
calibration_maskndarray of bool, shape (n_times,), or None, default=None: Samples to use from calibration data.
callbackcallable or None, default=None: Synchronous adaptive-calibration progress callback.
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

AdaptiveASR: The fitted estimator.

Fit adaptive ASR and transform the input.

For variant=”mw” and mw_mode=”sliding”, calibration and cleaning are performed per moving window. Other configurations compose fit and transform.

Parameters:

XRaw, Epochs, or ndarray: Data used for calibration and cleaning.
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.

Update the adaptive calibration state on a new chunk.

variant=”mw” is not supported by this method.

Parameters:

XRaw, Epochs, or ndarray: New calibration chunk.
yNone, default=None: Ignored for scikit-learn compatibility.
calibration_maskndarray of bool, shape (n_times,), or None, default=None: Samples to use from the chunk.
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

AdaptiveASR: The updated estimator.

reset_process_state() → None[source]#: Reset the streaming reconstruction state to the fitted baseline.

Apply the current adaptive ASR state.

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.