Add exclude parameter to raw.plot_psd() (mne-tools#9519)

* Add exclude parameter to raw.plot_psd()

* Fix tests and improve docstring

* Add changelog entry

* fix

Co-authored-by: Alexandre Gramfort <[email protected]>

doc/changes/latest.inc

@@ -81,6 +81,8 @@ Enhancements
 
 - Update :func:`mne.preprocessing.realign_raw` with Numpy-recommended polynomial fitting method (:gh:`9514` by `Erica Peterson`_)
 
+- Add ``exclude`` parameter to :meth:`mne.io.Raw.plot_psd` and :meth:`mne.Epochs.plot_psd` (:gh:`9519` by `Clemens Brunner`_)
+
 Bugs
 ~~~~
 - Fix bug with :meth:`mne.Epochs.crop` and :meth:`mne.Evoked.crop` when ``include_tmax=False``, where the last sample was always cut off, even when ``tmax > epo.times[-1]`` (:gh:`9378` **by new contributor** |Jan Sosulski|_)

mne/epochs.py

@@ -1127,7 +1127,7 @@ def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None,
                  xscale='linear', area_mode='std', area_alpha=0.33,
                  dB=True, estimate='auto', show=True, n_jobs=1,
                  average=False, line_alpha=None, spatial_colors=True,
-                 sphere=None, verbose=None):
+                 sphere=None, exclude='bads', verbose=None):
         return plot_epochs_psd(self, fmin=fmin, fmax=fmax, tmin=tmin,
                                tmax=tmax, proj=proj, bandwidth=bandwidth,
                                adaptive=adaptive, low_bias=low_bias,
@@ -1137,7 +1137,7 @@ def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None,
                                show=show, n_jobs=n_jobs, average=average,
                                line_alpha=line_alpha,
                                spatial_colors=spatial_colors, sphere=sphere,
-                               verbose=verbose)
+                               exclude=exclude, verbose=verbose)
 
     @copy_function_doc_to_method_doc(plot_epochs_psd_topomap)
     def plot_psd_topomap(self, bands=None, tmin=None,

mne/io/base.py

@@ -1511,7 +1511,7 @@ def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
                  area_mode='std', area_alpha=0.33, dB=True, estimate='auto',
                  show=True, n_jobs=1, average=False, line_alpha=None,
                  spatial_colors=True, sphere=None, window='hamming',
-                 verbose=None):
+                 exclude='bads', verbose=None):
         return plot_raw_psd(self, fmin=fmin, fmax=fmax, tmin=tmin, tmax=tmax,
                             proj=proj, n_fft=n_fft, n_overlap=n_overlap,
                             reject_by_annotation=reject_by_annotation,
@@ -1520,7 +1520,7 @@ def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
                             dB=dB, estimate=estimate, show=show, n_jobs=n_jobs,
                             average=average, line_alpha=line_alpha,
                             spatial_colors=spatial_colors, sphere=sphere,
-                            window=window, verbose=verbose)
+                            window=window, exclude=exclude, verbose=verbose)
 
     @copy_function_doc_to_method_doc(plot_raw_psd_topo)
     def plot_psd_topo(self, tmin=0., tmax=None, fmin=0, fmax=100, proj=False,

mne/viz/_figure.py

@@ -2383,7 +2383,8 @@ def _line_figure(inst, axes=None, picks=None, **kwargs):
 
 def _psd_figure(inst, proj, picks, axes, area_mode, tmin, tmax, fmin, fmax,
                 n_jobs, color, area_alpha, dB, estimate, average,
-                spatial_colors, xscale, line_alpha, sphere, window, **kwargs):
+                spatial_colors, xscale, line_alpha, sphere, window, exclude,
+                **kwargs):
     """Instantiate a new power spectral density figure."""
     from .. import BaseEpochs
     from ..io import BaseRaw
@@ -2409,7 +2410,7 @@ def _psd_figure(inst, proj, picks, axes, area_mode, tmin, tmax, fmin, fmax,
     _check_option('area_mode', area_mode, [None, 'std', 'range'])
     _check_option('xscale', xscale, ('log', 'linear'))
     sphere = _check_sphere(sphere, inst.info)
-    picks = _picks_to_idx(inst.info, picks)
+    picks = _picks_to_idx(inst.info, picks, exclude=exclude)
     titles = _handle_default('titles', None)
     units = _handle_default('units', None)
     scalings = _handle_default('scalings', None)

mne/viz/epochs.py

@@ -917,7 +917,7 @@ def plot_epochs_psd(epochs, fmin=0, fmax=np.inf, tmin=None, tmax=None,
                     xscale='linear', area_mode='std', area_alpha=0.33,
                     dB=True, estimate='auto', show=True, n_jobs=1,
                     average=False, line_alpha=None, spatial_colors=True,
-                    sphere=None, verbose=None):
+                    sphere=None, exclude='bads', verbose=None):
     """%(plot_psd_doc)s.
 
     Parameters
@@ -962,6 +962,12 @@ def plot_epochs_psd(epochs, fmin=0, fmax=np.inf, tmin=None, tmax=None,
     %(plot_psd_line_alpha)s
     %(plot_psd_spatial_colors)s
     %(topomap_sphere_auto)s
+    exclude : list of str | 'bads'
+        Channels names to exclude from being shown. If 'bads', the bad channels
+        are excluded. Pass an empty list to plot all channels (including
+        channels marked "bad", if any).
+
+        .. versionadded:: 0.24.0
     %(verbose)s
 
     Returns
@@ -981,6 +987,6 @@ def plot_epochs_psd(epochs, fmin=0, fmax=np.inf, tmin=None, tmax=None,
         line_alpha=line_alpha, area_alpha=area_alpha, color=color,
         spatial_colors=spatial_colors, n_jobs=n_jobs, bandwidth=bandwidth,
         adaptive=adaptive, low_bias=low_bias, normalization=normalization,
-        window='hamming')
+        window='hamming', exclude=exclude)
     plt_show(show)
     return fig

mne/viz/raw.py

@@ -373,7 +373,7 @@ def plot_raw_psd(raw, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
                  area_mode='std', area_alpha=0.33, dB=True, estimate='auto',
                  show=True, n_jobs=1, average=False, line_alpha=None,
                  spatial_colors=True, sphere=None, window='hamming',
-                 verbose=None):
+                 exclude='bads', verbose=None):
     """%(plot_psd_doc)s.
 
     Parameters
@@ -416,6 +416,12 @@ def plot_raw_psd(raw, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
     %(window-psd)s
 
         .. versionadded:: 0.22.0
+    exclude : list of str | 'bads'
+        Channels names to exclude from being shown. If 'bads', the bad channels
+        are excluded. Pass an empty list to plot all channels (including
+        channels marked "bad", if any).
+
+        .. versionadded:: 0.24.0
     %(verbose)s
 
     Returns
@@ -438,7 +444,7 @@ def plot_raw_psd(raw, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
         line_alpha=line_alpha, area_alpha=area_alpha, color=color,
         spatial_colors=spatial_colors, n_jobs=n_jobs, n_fft=n_fft,
         n_overlap=n_overlap, reject_by_annotation=reject_by_annotation,
-        window=window)
+        window=window, exclude=exclude)
     plt_show(show)
     return fig
 

mne/viz/tests/test_figure.py

@@ -15,4 +15,4 @@ def test_browse_figure_constructor():
 def test_psd_figure_constructor():
     """Test error handling in MNELineFigure constructor."""
     with pytest.raises(TypeError, match='an instance of Raw or Epochs, got'):
-        _psd_figure('foo', *((None,) * 19))
+        _psd_figure('foo', *((None,) * 20))

mne/viz/topomap.py

@@ -759,7 +759,7 @@ def plot_topomap(data, pos, vmin=None, vmax=None, cmap=None, sensors=True,
     %(topomap_border)s
     %(topomap_ch_type)s
 
-        ..versionadded:: 0.24.0
+        .. versionadded:: 0.24.0
     cnorm : matplotlib.colors.Normalize | None
         Colormap normalization, default None means linear normalization. If not
         None, ``vmin`` and ``vmax`` arguments are ignored. See Notes for more