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 (AASR) estimator.

This estimator extends the standard ASR algorithm by dynamically tracking the clean signal subspace over time. Three adaptive variants are exposed:

  • variant='psp': principal subspace projection updates (Hebbian)

  • variant='psw': principal subspace whitening updates (anti-Hebbian)

  • variant='mw': moving-window calibration updates

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.

  • variant ({'psw', 'psp'}, default='psw') – The adaptive update rule to use.

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

  • update_window_length (float, default=0.1) – RMS-statistics window length within each adaptive update segment. This is not the duration of the segment passed to partial_fit.

  • calibration_window_length (float, default=1.0) – 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 eigendecomposition.

  • max_dims (float | int, default=0.66) – Maximum fraction or absolute number of spatial dimensions to retain during reconstruction.

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

  • picks (str | list of str | list of int | slice | None, default='eeg') – Channels to include. Slices and lists of integers will be interpreted as channel indices.

  • reject_by_annotation (bool, default=True) – Whether to reject bad segments based on annotations during calibration.

  • skip_by_annotation (tuple of str, default=('bad', 'bad_acq_skip')) – If a string in this tuple is a prefix of an annotation description, that segment is ignored during calibration.

  • regularization (float, default=1e-8) – Ridge regularization added to covariance matrices to prevent singular inversions.

  • window_criterion (float | int | str | None, default=None) – Pre-rejection criterion for entirely bad windows. If a float, acts as a threshold multiplier.

  • window_criterion_tolerances (tuple of float, default=(-np.inf, 7.0)) – Tolerances for window_criterion testing.

  • lookahead (float | None, default=None) – Lookahead time in seconds for the sliding window reconstruction. Defaults to half the window length.

  • stepsize (int | None, default=None) – Stepsize in samples for the sliding window. Defaults to 32.

  • max_mem_mb (int | None, default=512) – Maximum memory (in megabytes) allowed for internal chunking operations.

  • copy (bool, default=True) – If True, data is copied before processing. If False, processing happens in place.

  • store_reconstruction_matrices (bool, default=False) – If True, the diagnostic dictionaries will contain the applied reconstruction mixing matrices.

  • learning_rate (float, default=0.2) – Step size parameter controlling how fast the subspace projection matrix incorporates new samples.

  • tau (float | None, default=None) – Time constant for the lateral connections (similarity tracking). If None, it defaults to 10.0 / learning_rate.

  • mw_window_length (float, default=20.0) – The length of the moving window (in seconds) over which covariance is aggregated before triggering adaptive updates.

  • mw_mode ({'final_state', 'cumulative'}, default='final_state') – Mode for moving-window aggregation.

  • random_state (int | None, default=None) – Random state for reproducibility in stochastic internal steps.

  • n_jobs (int | None, default=None) – Number of jobs to run in parallel.

  • verbose (bool | str | int | None, default=None) – Verbosity level.

__init__(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) → None[source]#

Methods

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

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

Fit the initial adaptive ASR state from calibration data.

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

Fit adaptive ASR and reconstruct X with the fitted state.

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.

partial_fit(X[, y, calibration_mask])

Update the adaptive calibration state on a new clean chunk.

reset_process_state()

Reset the streaming reconstruction state to the fitted baseline.

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_partial_fit_request(*[, calibration_mask])

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

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])

Clean data using the current adaptive ASR state.