mne_denoise.asr.process_guided_asr#

mne_denoise.asr.process_guided_asr(X: ndarray, sfreq: float, state: ASRState, *, artifact_cov: ndarray | None = None, preserve_cov: ndarray | None = None, reconstruction: str = 'soft', guidance_strength: float = 1.0, window_length: float = 0.5, window_overlap: float = 0.66, max_dims: float | int = 0.66, regularization: float = 1e-08, store_reconstruction_matrices: bool = False, max_mem_mb: int | None = 512, lookahead: float | None = None, stepsize: int | None = None) → tuple[ndarray, dict[str, Any]][source]#

Apply a calibrated ASR state with guided soft reconstruction.

This function follows the same streaming contract as mne_denoise.asr.process_asr(). It uses the shared windowed ASR processor and changes only the component keep weights.

Parameters:

  • X (ndarray, shape (n_channels, n_times)) – Continuous data in the channel order used for calibration.

  • sfreq (float) – Sampling frequency in Hz.

  • state (ASRState) – Fitted calibration state returned by mne_denoise.asr.calibrate_asr().

  • artifact_cov (ndarray, shape (n_channels, n_channels) | None) – Covariance describing directions that should be attenuated. The covariance is validated and symmetrized. Component scores are divided by its trace so only spatial structure affects guidance.

  • preserve_cov (ndarray, shape (n_channels, n_channels) | None) – Covariance describing directions that should be preserved. The covariance is validated and symmetrized. Component scores are divided by its trace so only spatial structure affects guidance.

  • reconstruction ({'soft', 'hard'}) – Reconstruction rule. 'soft' applies guidance-aware continuous weights. 'hard' exactly follows windowed ASR and requires both guidance covariances to be None.

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

  • window_length (float) – Processing window length in seconds.

  • window_overlap (float) – Accepted for parity with mne_denoise.asr.process_asr().

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

  • regularization (float) – Relative eigenvalue floor for covariance calculations.

  • store_reconstruction_matrices (bool) – If True, include per-window reconstruction matrices in diagnostics.

  • max_mem_mb (int | None) – Memory bound controlling full-stack versus rolling covariance updates.

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

  • stepsize (int | None) – Samples between reconstruction-matrix updates. None uses half a window.

Returns:

  • X_clean (ndarray, shape (n_channels, n_times)) – Reconstructed data.

  • diagnostics (dict) – Standard ASR processing diagnostics plus soft_weights, mean_soft_weight, and reconstruction.

See also

process_asr

Apply a calibrated standard ASR model.

GuidedASR

MNE- and scikit-learn-compatible guided estimator.

Notes

Soft GuidedASR is an unpublished and unvalidated research prototype. Its output must be evaluated independently for signal preservation and artifact attenuation.

Guidance changes only components for which variance >= threshold. Unflagged components retain weight one. For a flagged component, baseline soft-ASR weight is threshold / variance. Only a covariance score above the isotropic reference 1 / n_channels counts as directional evidence. The normalized preserve-minus-artifact evidence moves the weight toward one or zero under the linear control of guidance_strength.

Examples

Apply soft reconstruction after calibrating a state:

>>> clean, diagnostics = process_guided_asr(
...     data, sfreq=250.0, state=state, reconstruction="soft"
... )