mne_denoise.dss.DSS#

class mne_denoise.dss.DSS(bias: LinearDenoiser | Callable, n_components: int | None = None, n_select: int | str | None = None, selection_threshold: float = 3.0, knee_rel_floor: float = 0.01, knee_min_ratio: float = 3.0, rank: int | dict | None = None, reg: float = 1e-09, normalize_input: bool = True, cov_method: str = 'empirical', cov_kws: dict | None = None, smooth: LinearDenoiser | int | None = None, adaptive: bool = False, segmenter: CovarianceSegmenter | FixedWindowSegmenter | None = None, crossfade: float = 0.0, max_prop_remove: float | None = None, min_select: int = 0, component_action: str = 'extract', whiten: bool = False, noise_cov=None, verbose: bool | str | int | None = None, center: bool = True)[source]#

Denoising Source Separation (DSS) Transformer.

Implements DSS as a scikit-learn compatible transformer that fits natively on MNE-Python objects (Raw, Epochs, Evoked) or numpy arrays.

Parameters:

  • n_components (int, optional) – Number of DSS components to keep. If None, keep all.

  • bias (LinearDenoiser) – Bias function to define the signal of interest. Must be an instance of mne_denoise.dss.LinearDenoiser (e.g. BandpassBias, TrialAverageBias) or a callable that takes data and returns biased data.

  • n_select (int | 'auto' | None, default=None) – Number of significant components to auto-select after fitting. If 'auto', auto_select() determines the count via auto_select_components_robust() and stores it in n_selected_. If int, uses that exact number. If None (default), no automatic selection is performed — except when adaptive=True, where it defaults to 'auto' because per-segment adaptation is the whole point of that mode.

  • selection_threshold (float, default=3.0) – Sigma threshold for the outlier arm of automatic selection: components with eigenvalue > mean + sigma * std are significant. Same meaning as ZapLine(threshold=...).

  • knee_rel_floor (float, default=0.01) – Relative floor for the knee arm of automatic selection. Eigenvalues below this fraction of the largest are not considered valid knee anchors. Same meaning as ZapLine(knee_rel_floor=...).

  • knee_min_ratio (float, default=3.0) – Minimum drop ratio required to qualify as a knee, so that smoothly decaying (artifact-free) spectra select nothing. Same meaning as ZapLine(knee_min_ratio=...).

  • rank (int or dict, optional) – Rank of the data for whitening. If None, rank is estimated automatically.

  • reg (float) – Regularization for covariance estimation. Default 1e-9.

  • normalize_input (bool) – If True, normalize input data channel-wise (L2 norm) before fitting/transforming. Useful when mixing sensors with different scales (e.g. MAG and GRAD). Default True. Ignored when whiten=True (the whitener handles the scaling).

  • cov_method (str) – Method for covariance estimation. For MNE objects, passed as method to mne.compute_covariance. For NumPy arrays, selects the internal array covariance estimator. Default ‘empirical’.

  • cov_kws (dict, optional) – Additional keywords options for covariance estimation. For MNE objects, passed to mne.compute_covariance (e.g. {‘tstep’: 0.1, ‘rank’: ‘info’}). For NumPy arrays, passed to the internal array covariance estimator (e.g. {'shrinkage': 0.1}).

  • smooth (SmoothingBias | int | None, default=None) –

    Optional smoothing decomposition before DSS, inspired by ZapLine. When set, data is decomposed into smooth + residual and DSS is fitted/applied on the residual only. This dramatically increases eigenvalue contrast for narrowband artifacts because DSS no longer competes against broadband EEG variance.

    • If SmoothingBias instance: used directly.

    • If int: interpreted as the smoothing window in samples (e.g., int(sfreq / line_freq) for line noise).

    • If None (default): no smoothing, DSS is applied to the full data (original behavior).

  • adaptive (bool, default=False) –

    If True, data is split into segments and DSS is fitted independently per segment. This handles non-stationary artifacts whose spatial or spectral profile changes over time. The per-segment pathway runs in fit_transform(); fit() still produces a single global fit. Segmented fit_transform() requires component_action='subtract' because component bases differ between segments.

    This is the same switch ZapLine exposes as adaptive, which inherits this parameter directly.

  • segmenter (CovarianceSegmenter | FixedWindowSegmenter | None, default=None) – Segmentation strategy. If None and adaptive=True, a CovarianceSegmenter is created automatically (requires sfreq to be determinable from the input or from the bias function).

  • crossfade (float, default=0.0) – Duration (in seconds) of the cross-fade at segment boundaries when adaptive=True. Adjacent segments are extended by this amount on each side, cleaned independently, then blended using a raised-cosine (Hann) overlap-add window. This eliminates discontinuities at segment boundaries. If 0.0 (default), segments are hard-concatenated, matching ZapLine-plus, which concatenates cleaned chunks directly (Klug & Kloosterman, 2022); the cross-fade is an mne-denoise addition for smoother boundaries. Typical values: 0.5 – 2.0 s.

  • max_prop_remove (float | None, default=None) – Maximum proportion of channels that can be removed per segment. E.g. 0.2 caps n_selected at int(n_channels × 0.2). Safety valve to prevent over-cleaning; mirrors ZapLine-plus, which caps the automatic component count at one-fifth of the channels (Klug & Kloosterman, 2022, §2.4).

  • min_select (int, default=0) – Minimum components to select when n_select='auto' and the artifact is present. Guarantees a floor on cleaning strength. Only effective when adaptive=True. Mirrors ZapLine-plus’s fixed-removal floor (fixedNremove; Klug & Kloosterman, 2022).

  • component_action ({'extract', 'retain', 'subtract'}, default='extract') – Explicit operation applied to DSS components. 'extract' returns component time courses. 'retain' reconstructs the leading selected components in sensor space. 'subtract' removes them from the input. n_select controls the number retained or subtracted; when it is None, retention uses every fitted component and subtraction is an exact no-op. In adaptive fit_transform(), only subtraction is supported because each segment has a different fitted basis.

  • whiten (bool, default=False) – If True, decompose all data channel types jointly (e.g. mag + grad + eeg) instead of isolating a single homogeneous type. The data is whitened before the DSS bias/covariance step and un-whitened on reconstruction, so channels with different physical units no longer contaminate one another.

  • noise_cov (mne.Covariance | None, default=None) – Noise covariance used to build the whitener when whiten=True (MNE inputs only). If None, MNE inputs are scaled by channel type, matching MNE’s ICA pre-whitening fallback; NumPy arrays are scaled per channel. Ignored when whiten=False.

  • verbose (bool | str | int | None, default=None) – Control logging verbosity.

  • center (bool, default=True) – If True, subtract one global channel mean fitted on the training data and reuse it for every transform. If False, use uncentered second moments. Transform batches are never centered from their own data.

filters_#

The spatial filters (un-mixing matrix).

Type:

array, shape (n_components, n_channels)

patterns_#

The spatial patterns (mixing matrix).

Type:

array, shape (n_channels, n_components)

eigenvalues_#

The power of each component in the biased data (bias score).

Type:

array, shape (n_components,)

mean_#

Global training mean reused by transform(), or zeros when center=False.

Type:

array, shape (n_channels, 1)

n_selected_#

Number of significant components detected by automatic selection. Only set when n_select is not None. Use this to determine how many components to remove/keep in downstream processing.

Type:

int | None

segment_results_#

Per-segment metadata when adaptive=True. Each dict contains 'start', 'end', 'n_selected', 'eigenvalues', and 'patterns'.

Type:

list of dict | None

Examples

>>> from mne_denoise.dss import DSS, BandpassBias
>>> from mne_denoise.dss.denoisers import TrialAverageBias
>>> # Create a bias (e.g. emphasize 10Hz oscillations)
>>> bias = BandpassBias(sfreq=250, freq=10, bandwidth=2)
>>> # Initialize DSS
>>> dss = DSS(bias=bias, n_components=3, component_action="extract")
>>> # Fit on data (MNE Raw/Epochs or NumPy)
>>> dss.fit(raw_data)
>>> # Extract sources
>>> sources = dss.transform(raw_data)
>>> # Or remove the leading biased component in sensor space
>>> cleaner = DSS(
...     bias=bias,
...     n_components=3,
...     n_select=1,
...     component_action="subtract",
... )
>>> denoised_raw = cleaner.fit_transform(raw_data)

See also

compute_dss

Functional interface for computing DSS solutions.

__init__(bias: LinearDenoiser | Callable, n_components: int | None = None, n_select: int | str | None = None, selection_threshold: float = 3.0, knee_rel_floor: float = 0.01, knee_min_ratio: float = 3.0, rank: int | dict | None = None, reg: float = 1e-09, normalize_input: bool = True, cov_method: str = 'empirical', cov_kws: dict | None = None, smooth: LinearDenoiser | int | None = None, adaptive: bool = False, segmenter: CovarianceSegmenter | FixedWindowSegmenter | None = None, crossfade: float = 0.0, max_prop_remove: float | None = None, min_select: int = 0, component_action: str = 'extract', whiten: bool = False, noise_cov=None, verbose: bool | str | int | None = None, center: bool = True) → None[source]#

Methods

__init__(bias[, n_components, n_select, ...])

auto_select([threshold])

Automatically determine how many DSS components are significant.

fit(X[, y, weights])

Compute DSS spatial filters.

fit_transform(X[, y])

Fit and apply the configured component operation.

get_metadata_routing()

Get metadata routing of this object.

get_normalized_patterns()

Get L2-normalized spatial patterns for visualization.

get_params([deep])

Get parameters for this estimator.

inverse_transform(sources[, component_indices])

Transform sources back to sensor space.

set_fit_request(*[, weights])

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

set_inverse_transform_request(*[, ...])

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

set_output(*[, transform])

Set output container.

set_params(**params)

Set the parameters of this estimator.

transform(X)

Apply the configured DSS component operation.