Remove legacy plot_psd* funcs/methods in our docs and codebase (mne-tools#11563)

Author: drammock

doc/changes/latest.inc

@@ -55,6 +55,7 @@ Bugs
 - Fix visualization dialog compatibility with matplotlib 3.7 (:gh:`11409` by `Daniel McCloy`_ and `Eric Larson`_)
 - Expand tilde (user directory) in config keys (:gh:`11537` by `Clemens Brunner`_)
 - Fix bug in :func:`mne.preprocessing.compute_maxwell_basis` where using ``int_order=0`` would raise an error (:gh:`11562` by `Eric Larson`_)
+- In the legacy function :func:`mne.viz.plot_epochs_psd_topomap`, the parameter ``names`` now works again (:gh:`11563` by `Daniel McCloy`_)
 - Fix :func:`mne.io.read_raw` for file names containing multiple dots (:gh:`11521` by `Clemens Brunner`_)
 - Fix bug in :func:`mne.export.export_raw` when exporting to EDF with a physical range set smaller than the data range (:gh:`11569` by `Mathieu Scheltienne`_)
 - Fix bug in :func:`mne.concatenate_raws` where two raws could not be merged if the order of the bad channel lists did not match (:gh:`11502` by `Moritz Gerster`_)

examples/datasets/brainstorm_data.py

@@ -42,7 +42,7 @@
 raw.set_eeg_reference('average', projection=True)
 
 # show power line interference and remove it
-raw.plot_psd(tmax=60., average=False)
+raw.compute_psd(tmax=60).plot(average=False)
 raw.notch_filter(np.arange(60, 181, 60), fir_design='firwin')
 
 events = mne.find_events(raw, stim_channel='UPPT001')

examples/preprocessing/eeg_csd.py

@@ -50,8 +50,8 @@
 # %%
 # Also look at the power spectral densities:
 
-raw.plot_psd()
-raw_csd.plot_psd()
+raw.compute_psd().plot()
+raw_csd.compute_psd().plot()
 
 # %%
 # CSD can also be computed on Evoked (averaged) data.

examples/preprocessing/find_ref_artifacts.py

@@ -63,7 +63,7 @@
 
 # %%
 # The PSD of these data show the noise as clear peaks.
-raw.plot_psd(fmax=30)
+raw.compute_psd(fmax=30).plot()
 
 # %%
 # Run the "together" algorithm.
@@ -93,7 +93,7 @@
 
 # %%
 # Cleaned data:
-raw_tog.plot_psd(fmax=30)
+raw_tog.compute_psd(fmax=30).plot()
 
 # %%
 # Now try the "separate" algorithm.
@@ -138,7 +138,7 @@
 # %%
 # Cleaned raw data PSD:
 
-raw_sep.plot_psd(fmax=30)
+raw_sep.compute_psd(fmax=30).plot()
 
 ##############################################################################
 # References

examples/time_frequency/source_power_spectrum_opm.py

@@ -79,7 +79,7 @@
 n_fft = next_fast_len(int(round(4 * new_sfreq)))
 print('Using n_fft=%d (%0.1f s)' % (n_fft, n_fft / raws['vv'].info['sfreq']))
 for kind in kinds:
-    fig = raws[kind].plot_psd(n_fft=n_fft, proj=True)
+    fig = raws[kind].compute_psd(n_fft=n_fft, proj=True).plot()
     fig.suptitle(titles[kind])
     fig.subplots_adjust(0.1, 0.1, 0.95, 0.85)
 

examples/visualization/sensor_noise_level.py

@@ -25,8 +25,8 @@
 
 # %%
 # We can plot the absolute noise levels:
-raw_erm.plot_psd(tmax=10., average=True, spatial_colors=False,
-                 dB=False, xscale='log')
+raw_erm.compute_psd(tmax=10).plot(average=True, spatial_colors=False,
+                                  dB=False, xscale='log')
 # %%
 # References
 # ----------

mne/io/array/tests/test_array.py

@@ -143,8 +143,8 @@ def test_array_raw():
 
     # plotting
     raw2.plot()
-    raw2.plot_psd(tmax=2., average=True, n_fft=1024,
-                  spatial_colors=False)
+    (raw2.compute_psd(tmax=2., n_fft=1024)
+         .plot(average=True, spatial_colors=False))
     plt.close('all')
 
     # epoching
@@ -177,5 +177,6 @@ def test_array_raw():
 
     raw = RawArray(data, info)
     raw.set_montage(montage)
-    raw.plot_psd(average=False)  # looking for nonexistent layout
-    raw.plot_psd_topo()
+    spectrum = raw.compute_psd()
+    spectrum.plot(average=False)  # looking for nonexistent layout
+    spectrum.plot_topo()

mne/report/report.py

@@ -41,6 +41,7 @@
                      _path_like, use_log_level, _check_fname, _pl,
                      _check_ch_locs, _import_h5io_funcs, _verbose_safe_false,
                      check_version)
+from ..utils.spectrum import _split_psd_kwargs
 from ..viz import (plot_events, plot_alignment, plot_cov, plot_projs_topomap,
                    plot_compare_evokeds, set_3d_view, get_3d_backend,
                    Figure3D, use_browser_backend)
@@ -687,9 +688,11 @@ class Report:
     raw_psd : bool | dict
         If True, include PSD plots for raw files. Can be False (default) to
         omit, True to plot, or a dict to pass as ``kwargs`` to
-        :meth:`mne.io.Raw.plot_psd`.
+        :meth:`mne.time_frequency.Spectrum.plot`.
 
         .. versionadded:: 0.17
+        .. versionchanged:: 1.4
+           kwargs are sent to ``spectrum.plot`` instead of ``raw.plot_psd``.
     projs : bool
         Whether to include topographic plots of SSP projectors, if present in
         the data. Defaults to ``False``.
@@ -717,9 +720,11 @@ class Report:
     raw_psd : bool | dict
         If True, include PSD plots for raw files. Can be False (default) to
         omit, True to plot, or a dict to pass as ``kwargs`` to
-        :meth:`mne.io.Raw.plot_psd`.
+        :meth:`mne.time_frequency.Spectrum.plot`.
 
         .. versionadded:: 0.17
+        .. versionchanged:: 1.4
+           kwargs are sent to ``spectrum.plot`` instead of ``raw.plot_psd``.
     projs : bool
         Whether to include topographic plots of SSP projectors, if present in
         the data. Defaults to ``False``.
@@ -2837,7 +2842,11 @@ def _add_raw(
             else:
                 fmax = np.inf
 
-            fig = raw.plot_psd(fmax=fmax, show=False, **add_psd)
+            # shim: convert legacy .plot_psd(...) → .compute_psd(...).plot(...)
+            init_kwargs, plot_kwargs = _split_psd_kwargs(kwargs=add_psd)
+            init_kwargs.setdefault('fmax', fmax)
+            plot_kwargs.setdefault('show', False)
+            fig = raw.compute_psd(**init_kwargs).plot(**plot_kwargs)
             tight_layout(fig=fig)
             _constrain_fig_resolution(
                 fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES
@@ -3358,7 +3367,7 @@ def _add_epochs_psd(
             if fmax > 0.5 * epochs.info['sfreq']:
                 fmax = np.inf
 
-        fig = epochs_for_psd.plot_psd(fmax=fmax, show=False)
+        fig = epochs_for_psd.compute_psd(fmax=fmax).plot(show=False)
         _constrain_fig_resolution(
             fig, max_width=MAX_IMG_WIDTH, max_res=MAX_IMG_RES
         )

mne/report/tests/test_report.py

@@ -359,6 +359,9 @@ def test_report_raw_psd_and_date(tmp_path):
     assert 'Unknown' not in ''.join(report.html)
     assert 'GMT' in ''.join(report.html)
 
+    # test kwargs passed through to underlying array func
+    Report(raw_psd=dict(window='boxcar'))
+
     # test new anonymize functionality
     report = Report()
     raw.anonymize()

mne/time_frequency/spectrum.py

@@ -24,6 +24,7 @@
 from ..utils.check import (_check_fname, _check_option, _import_h5io_funcs,
                            _is_numeric, check_fname)
 from ..utils.misc import _pl
+from ..utils.spectrum import _split_psd_kwargs
 from ..viz.topo import _plot_timeseries, _plot_timeseries_unified, _plot_topo
 from ..viz.topomap import (_make_head_outlines, _prepare_topomap_plot,
                            plot_psds_topomap)
@@ -92,29 +93,8 @@ def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None, picks=None,
         -----
         %(notes_plot_psd_meth)s
         """
-        from ..io import BaseRaw
-
-        # triage reject_by_annotation
-        rba = dict()
-        if isinstance(self, BaseRaw):
-            rba = dict(reject_by_annotation=reject_by_annotation)
-
-        spectrum = self.compute_psd(
-            method=method, fmin=fmin, fmax=fmax, tmin=tmin, tmax=tmax,
-            picks=picks, proj=proj, n_jobs=n_jobs, verbose=verbose, **rba,
-            **method_kw)
-
-        # translate kwargs
-        amplitude = 'auto' if estimate == 'auto' else (estimate == 'amplitude')
-        ci = 'sd' if area_mode == 'std' else area_mode
-        # ↓ here picks="all" because we've already restricted the `info` to
-        # ↓ have only `picks` channels
-        fig = spectrum.plot(
-            picks='all', average=average, dB=dB, amplitude=amplitude,
-            xscale=xscale, ci=ci, ci_alpha=area_alpha, color=color,
-            alpha=line_alpha, spatial_colors=spatial_colors, sphere=sphere,
-            exclude=exclude, axes=ax, show=show)
-        return fig
+        init_kw, plot_kw = _split_psd_kwargs(plot_fun=Spectrum.plot)
+        return self.compute_psd(**init_kw).plot(**plot_kw)
 
     @legacy(alt='.compute_psd().plot_topo()')
     @verbose
@@ -148,13 +128,8 @@ def plot_psd_topo(self, tmin=None, tmax=None, fmin=0, fmax=100, proj=False,
         fig : instance of matplotlib.figure.Figure
             Figure distributing one image per channel across sensor topography.
         """
-        spectrum = self.compute_psd(
-            method=method, fmin=fmin, fmax=fmax, tmin=tmin, tmax=tmax,
-            proj=proj, n_jobs=n_jobs, verbose=verbose, **method_kw)
-
-        return spectrum.plot_topo(
-            dB=dB, layout=layout, color=color, fig_facecolor=fig_facecolor,
-            axis_facecolor=axis_facecolor, axes=axes, block=block, show=show)
+        init_kw, plot_kw = _split_psd_kwargs(plot_fun=Spectrum.plot_topo)
+        return self.compute_psd(**init_kw).plot_topo(**plot_kw)
 
     @legacy(alt='.compute_psd().plot_topomap()')
     @verbose
@@ -212,19 +187,8 @@ def plot_psd_topomap(self, bands=None, tmin=None, tmax=None, ch_type=None,
         fig : instance of Figure
             Figure showing one scalp topography per frequency band.
         """
-        spectrum = self.compute_psd(
-            method=method, tmin=tmin, tmax=tmax, proj=proj,
-            n_jobs=n_jobs, verbose=verbose, **method_kw)
-
-        fig = spectrum.plot_topomap(
-            bands=bands, ch_type=ch_type, normalize=normalize, agg_fun=agg_fun,
-            dB=dB, sensors=sensors, show_names=show_names, mask=mask,
-            mask_params=mask_params, contours=contours, outlines=outlines,
-            sphere=sphere, image_interp=image_interp, extrapolate=extrapolate,
-            border=border, res=res, size=size, cmap=cmap, vlim=vlim,
-            cnorm=cnorm, colorbar=colorbar, cbar_fmt=cbar_fmt, units=units,
-            axes=axes, show=show)
-        return fig
+        init_kw, plot_kw = _split_psd_kwargs(plot_fun=Spectrum.plot_topomap)
+        return self.compute_psd(**init_kw).plot_topomap(**plot_kw)
 
     def _set_legacy_nfft_default(self, tmin, tmax, method, method_kw):
         """Update method_kw with legacy n_fft default for plot_psd[_topo]().
@@ -912,9 +876,8 @@ class Spectrum(BaseSpectrum):
     .. footbibliography::
     """
 
-    def __init__(self, inst, method, fmin, fmax, tmin, tmax, picks,
-                 proj, reject_by_annotation, *, n_jobs, verbose=None,
-                 **method_kw):
+    def __init__(self, inst, method, fmin, fmax, tmin, tmax, picks, proj,
+                 reject_by_annotation, *, n_jobs, verbose=None, **method_kw):
         from ..io import BaseRaw
 
         # triage reading from file