mne_denoise.viz.plot_component_selector#

Plot an interactive component selector for DSS or standard ZapLine.

Each component row contains its spatial pattern, time course, and power spectrum. Left-clicking a row toggles whether the component is excluded and updates the optional reconstruction preview. Rows excluded from the clean output are tinted red.

Anywhere in a component’s row responds to the click, including the margins around the topomap and the label above it.

Matplotlib canvases cannot scroll, so decompositions with more components than rows_per_page are paged rather than stretched off-screen. Click a page button above the rows to jump to that page; the scroll wheel and PageUp/PageDown (also Home/End) work too. Past eight pages the buttons compact to prev/next arrows with a counter. The selection is global: paging never discards toggles made on another page.

Parameters:

estimator (DSS | IterativeDSS | ZapLine) – Fitted estimator. ZapLine must use standard mode (adaptive=False).
data (Raw | Epochs | Evoked | ndarray) – Data used to compute component sources and the live preview.
info (mne.Info | None, default=None) – Sensor metadata. This can be inferred from a fitted estimator for the sampling frequency, but topomaps require both explicit info and explicit picks.
picks (array-like of int | None, default=None) – Channel indices used for topomaps. Requires an explicitly supplied info. If None, the spatial-pattern panels contain a placeholder.
times (array | None, default=None) – Time coordinates for component traces. The length must match the per-epoch time dimension, or the continuous sample count for Raw, Evoked, and two-dimensional arrays. If None, sample indices are used.
n_components (int | array-like of int | None, default=None) – Components displayed and made clickable. An integer selects the first requested components; a sequence selects explicit component indices. If None, all fitted components are selectable, spread over pages.
rows_per_page (int, default=3) – Component rows drawn per page. This fixes the figure height regardless of how many components are selectable.
preview (bool, default=True) – Add a live reference/selection GFP and PSD preview.
sfreq (float | None, default=None) – Sampling frequency used for PSDs when info is unavailable.
psd_fmax (float | None, default=None) – Maximum PSD frequency. If None, use min(100, sfreq / 2).
show (bool, default=True) – Show the figure.
fname (path-like | None, default=None) – Optional path at which to save the figure.

Returns:

selector – Selection controller. Read selector.excluded and call selector.apply() to obtain the current reconstruction.

Return type:

ComponentSelector

Raises:

TypeError – If estimator is not a supported estimator.
RuntimeError – If the estimator is not fitted.
NotImplementedError – If adaptive ZapLine is supplied.
ValueError – If the data, plotting coordinates, or frequency parameters are invalid.

Notes

For DSS and IterativeDSS, red components are omitted from the reconstruction. With no exclusions, the output is the fitted DSS-subspace reconstruction with the input channel means restored; it equals the input only for a complete reconstruction. For standard ZapLine, red components are noise components subtracted from the input, and all fitted noise components start excluded.

The preview therefore compares the current selection against the no-exclusion reconstruction, not against the raw input. For a rank-reduced DSS fit those two differ by the discarded subspace, which would otherwise swamp the effect of the toggles being previewed; the panel titles report that rank. For ZapLine the no-exclusion reconstruction is the input itself, so the comparison is the familiar before/after.

n_components controls only which already-fitted components are displayed; it does not refit an estimator. In particular, the selector can restore fitted ZapLine components but cannot expose components discarded during fit.

NumPy layout follows the estimator APIs: Linear DSS accepts channel-first epoched arrays (n_channels, n_times, n_epochs); IterativeDSS and ZapLine accept MNE-style arrays (n_epochs, n_channels, n_times).

Examples

>>> from mne_denoise.viz import plot_component_selector
>>> selector = plot_component_selector(
...     dss,
...     epochs,
...     info=epochs.info,
...     picks=[0, 1, 2, 3],
...     times=epochs.times,
... )
>>> cleaned = selector.apply()