mne_denoise.qa.below_noise_distortion_db#

mne_denoise.qa.below_noise_distortion_db(freqs: ndarray, psd_before: ndarray, psd_after: ndarray, exclude_freq: float | None = None, exclude_bw: float = 5.0, fmin: float = 1.0, fmax: float = 45.0, n_harmonics: int = 0) → ndarray[source]#

Broadband spectral distortion (dB) outside excluded noise bands.

Computed as the mean absolute log-ratio: |10 * log10(psd_after / psd_before)| over selected frequencies. Lower values indicate less collateral broadband distortion.

Parameters:

  • freqs (array of shape (n_freqs,)) – Frequency vector.

  • psd_before (array of shape (n_channels, n_freqs) or (n_freqs,)) – PSD before cleaning.

  • psd_after (array of shape (n_channels, n_freqs) or (n_freqs,)) – PSD after cleaning.

  • exclude_freq (float | None) – Fundamental line-noise frequency to exclude (together with its harmonics). If None no exclusion is applied.

  • exclude_bw (float) – Half-bandwidth (Hz) to exclude around each harmonic.

  • fmin (float) – Frequency range for the broadband comparison.

  • fmax (float) – Frequency range for the broadband comparison.

  • n_harmonics (int) – Number of harmonics of exclude_freq to also exclude (0 = fundamental only).

Returns:

distortion – Per-channel distortion for 2D PSD input, or a scalar for 1D PSD input.

Return type:

ndarray | float

Notes

This metric is useful as a signal-preservation indicator while line-noise-focused metrics capture artifact suppression.

Examples

>>> import numpy as np
>>> from mne_denoise.qa import below_noise_distortion_db
>>> freqs = np.arange(0, 100, 0.5)
>>> before = np.ones((2, len(freqs)))
>>> after = before.copy()
>>> np.allclose(below_noise_distortion_db(freqs, before, after), 0.0)
True