Mark legacy (#11121)

* mark several funcs/methods as legacy

* update comment

* nicer info message

Author: drammock

mne/time_frequency/spectrum.py

@@ -21,7 +21,7 @@
 from ..utils import (GetEpochsMixin, _build_data_frame,
                      _check_pandas_index_arguments, _check_pandas_installed,
                      _check_sphere, _time_mask, _validate_type, fill_doc,
-                     logger, object_diff, verbose, warn)
+                     legacy, logger, object_diff, verbose, warn)
 from ..utils.check import (_check_fname, _check_option, _import_h5io_funcs,
                            _is_numeric, check_fname)
 from ..utils.misc import _pl
@@ -40,6 +40,7 @@ def _identity_function(x):
 class SpectrumMixin():
     """Mixin providing spectral plotting methods to sensor-space containers."""
 
+    @legacy(alt='.compute_psd().plot()')
     @verbose
     def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None, picks=None,
                  proj=False, reject_by_annotation=True, *, method='auto',
@@ -116,6 +117,7 @@ def plot_psd(self, fmin=0, fmax=np.inf, tmin=None, tmax=None, picks=None,
             exclude=exclude, axes=ax, show=show)
         return fig
 
+    @legacy(alt='.compute_psd().plot_topo()')
     @verbose
     def plot_psd_topo(self, tmin=None, tmax=None, fmin=0, fmax=100, proj=False,
                       *, method='auto', dB=True, layout=None, color='w',
@@ -157,6 +159,7 @@ def plot_psd_topo(self, tmin=None, tmax=None, fmin=0, fmax=100, proj=False,
             dB=dB, layout=layout, color=color, fig_facecolor=fig_facecolor,
             axis_facecolor=axis_facecolor, axes=axes, block=block, show=show)
 
+    @legacy(alt='.compute_psd().plot_topomap()')
     @verbose
     def plot_psd_topomap(self, bands=None, tmin=None, tmax=None, proj=False,
                          method='auto', ch_type=None, *, normalize=False,

mne/utils/docs.py

@@ -4168,7 +4168,7 @@ class _decorator:
     def __init__(self, extra):  # noqa: D102
         self.kind = self.__class__.__name__
         self.extra = extra
-        self.msg = f'{{}} is a {self.kind} {{}}. {self.extra}.'
+        self.msg = f'NOTE: {{}}() is a {self.kind} {{}}. {self.extra}.'
 
     def __call__(self, obj):  # noqa: D105
         """Call.

mne/viz/epochs.py

@@ -20,7 +20,7 @@
 from .raw import _setup_channel_selections
 from ..fixes import _sharex
 from ..defaults import _handle_default
-from ..utils import verbose, logger, warn, fill_doc, _check_option
+from ..utils import legacy, verbose, logger, warn, fill_doc, _check_option
 from ..io.meas_info import create_info, _validate_type
 
 from ..io.pick import (_get_channel_types, _picks_to_idx, _DATA_CH_TYPES_SPLIT,
@@ -922,6 +922,7 @@ def plot_epochs(epochs, picks=None, scalings=None, n_epochs=20, n_channels=20,
     return fig
 
 
+@legacy(alt='Epochs.compute_psd().plot()')
 @verbose
 def plot_epochs_psd(epochs, fmin=0, fmax=np.inf, tmin=None, tmax=None,
                     proj=False, bandwidth=None, adaptive=False, low_bias=True,

mne/viz/raw.py

@@ -13,7 +13,7 @@
 from ..annotations import _annotations_starts_stops
 from ..filter import create_filter
 from ..io.pick import pick_types, pick_channels
-from ..utils import verbose, _validate_type, _check_option
+from ..utils import legacy, verbose, _validate_type, _check_option
 from ..defaults import _handle_default
 from .utils import (_compute_scalings, _handle_decim, _check_cov,
                     _shorten_path_from_middle, _handle_precompute,
@@ -357,6 +357,7 @@ def plot_raw(raw, events=None, duration=10.0, start=0.0, n_channels=20,
     return fig
 
 
+@legacy(alt='Raw.compute_psd().plot()')
 @verbose
 def plot_raw_psd(raw, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
                  n_fft=None, n_overlap=0, reject_by_annotation=True,
@@ -426,6 +427,7 @@ def plot_raw_psd(raw, fmin=0, fmax=np.inf, tmin=None, tmax=None, proj=False,
     return fig
 
 
+@legacy(alt='Raw.compute_psd().plot_topo()')
 @verbose
 def plot_raw_psd_topo(raw, tmin=0., tmax=None, fmin=0., fmax=100., proj=False,
                       *, n_fft=2048, n_overlap=0, dB=True, layout=None,

mne/viz/topomap.py

@@ -28,7 +28,7 @@
                        _MEG_CH_TYPES_SPLIT)
 from ..utils import (_clean_names, _time_mask, verbose, logger, fill_doc,
                      _validate_type, _check_sphere, _check_option, _is_numeric,
-                     warn)
+                     warn, legacy)
 from .utils import (tight_layout, _setup_vmin_vmax, _prepare_trellis,
                     _check_delayed_ssp, _draw_proj_checkbox, figure_nobar,
                     plt_show, _process_times, DraggableColorbar, _get_cmap,
@@ -1940,6 +1940,7 @@ def _plot_topomap_multi_cbar(data, pos, ax, title=None, unit=None, vmin=None,
         cbar.ax.tick_params(labelsize=8)
 
 
+@legacy(alt='Epochs.compute_psd().plot_topomap()')
 @verbose
 def plot_epochs_psd_topomap(epochs, bands=None, tmin=None, tmax=None,
                             proj=False, *, bandwidth=None, adaptive=False,

mne/viz/utils.py

@@ -2212,7 +2212,7 @@ def _plot_psd(inst, fig, freqs, psd_list, picks_list, titles_list,
               units_list, scalings_list, ax_list, make_label, color, area_mode,
               area_alpha, dB, estimate, average, spatial_colors, xscale,
               line_alpha, sphere, xlabels_list):
-    # helper function for plot_raw_psd and plot_epochs_psd
+    # helper function for Spectrum.plot()
     from matplotlib.ticker import ScalarFormatter
     from .evoked import _plot_lines
     from ..stats import _ci