API: Deprecate mayavi

doc/changes/latest.inc

@@ -315,6 +315,14 @@ API changes
 ~~~~~~~~~~~
 - The :class:`mne.Info` class is now more strictly checked when attributes are set. Setting most attributes directly will lead to an error in the next release. See the docstring of :class:`mne.Info` for more information (:gh:`9867` **by new contributor** |Mathieu Scheltienne|_)
 
+- The Mayavi 3D backend has been deprecated (:gh:`9904` by `Eric Larson`_):
+
+  - In 3D plotting functions, use PyVista-based backends (``'pyvistaqt'`` and ``'notebook'``) as PySurfer/Mayavi will be removed in the next version
+
+  - To use the :ref:`mne kit2fiff` command-line GUI for fiducial markers, install the separate ``mne-kit-gui`` module, which can still be launched via ``$ mne kit2fiff``
+
+  - The ``mne.gui.fiducials`` GUI has been deprecated, use :ref:`mne coreg` or ``mne_kit_gui.fiducials()`` to set MRI fiducials instead
+
 - In `mne.compute_source_morph`, the ``niter_affine`` and ``niter_sdr`` parameters have been replaced by ``niter`` and ``pipeline`` parameters for more consistent and finer-grained control of registration/warping steps and iteration (:gh:`9505` by `Alex Rockhill`_ and `Eric Larson`_)
 
 - Split :func:`mne.viz.Brain.show_view` argument ``view`` into ``azimuth``, ``elevation`` and ``focalpoint`` for clearer view setting and make the default for ``row`` and ``col`` apply to all rows and columns (:gh:`9596` by `Alex Rockhill`_)

doc/mri.rst

@@ -18,7 +18,6 @@ Step by step instructions for using :func:`gui.coregistration`:
    coreg.estimate_head_mri_t
    get_montage_volume_labels
    gui.coregistration
-   gui.fiducials
    gui.locate_ieeg
    create_default_subject
    head_to_mni

examples/datasets/spm_faces_dataset_sgskip.py

@@ -131,7 +131,7 @@
 stc = apply_inverse(contrast, inverse_operator, lambda2, method, pick_ori=None)
 # stc.save('spm_%s_dSPM_inverse' % contrast.comment)
 
-# Plot contrast in 3D with PySurfer if available
+# Plot contrast in 3D with mne.viz.Brain if available
 brain = stc.plot(hemi='both', subjects_dir=subjects_dir, initial_time=0.170,
                  views=['ven'], clim={'kind': 'value', 'lims': [3., 6., 9.]})
 # brain.save_image('dSPM_map.png')

examples/inverse/label_from_stc.py

@@ -98,7 +98,7 @@
 plt.show()
 
 # %%
-# plot brain in 3D with PySurfer if available
+# plot brain in 3D with mne.viz.Brain if available
 brain = stc_mean.plot(hemi='lh', subjects_dir=subjects_dir)
 brain.show_view('lateral')
 

mne/commands/mne_kit2fiff.py

@@ -17,7 +17,9 @@
 
 """
 
+from contextlib import nullcontext
 import sys
+import warnings
 
 import mne
 from mne.io import read_raw_kit
@@ -60,8 +62,15 @@ def run():
 
     input_fname = options.input_fname
     if input_fname is None:
-        with ETSContext():
-            mne.gui.kit2fiff()
+        ctx = nullcontext()
+        try:
+            from mne_kit_gui import kit2fiff  # noqa
+        except ImportError:
+            kit2fiff = mne.gui.kit2fiff
+            ctx = ETSContext()
+        with ctx, warnings.catch_warnings():
+            warnings.simplefilter('always', DeprecationWarning)
+            kit2fiff()
         sys.exit(0)
 
     hsp_fname = options.hsp_fname

mne/conftest.py

@@ -130,6 +130,7 @@ def pytest_configure(config):
     ignore:.*Passing a schema to Validator.*:DeprecationWarning
     ignore:.*Found the following unknown channel type.*:RuntimeWarning
     ignore:.*in an Any trait will be shared.*:DeprecationWarning
+    ignore:.*Mayavi 3D backend is deprecated.*:DeprecationWarning
     always::ResourceWarning
     """  # noqa: E501
     for warning_line in warning_lines.split('\n'):

mne/gui/__init__.py

@@ -6,7 +6,8 @@
 
 import os
 
-from ..utils import _check_mayavi_version, verbose, get_config, warn
+from ..utils import (_check_mayavi_version, verbose, get_config, warn,
+                     deprecated)
 from ._backend import _testing_mode
 
 
@@ -228,6 +229,8 @@ def coregistration(tabbed=False, split=True, width=None, inst=None,
         return _initialize_gui(frame, view)
 
 
+@deprecated('The `fiducials` function has moved to the separate mne-kit-gui '
+            'module and will be removed from mne after 0.24.')
 def fiducials(subject=None, fid_file=None, subjects_dir=None):
     """Set the fiducials for an MRI subject.
 
@@ -259,6 +262,9 @@ def fiducials(subject=None, fid_file=None, subjects_dir=None):
     return _initialize_gui(frame)
 
 
+@deprecated('The `mne kit2fiff` command will require the mne-kit-gui '
+            'module after 0.24, install it using conda-forge or pip to '
+            'continue using this utility.')
 def kit2fiff():
     """Convert KIT files to the fiff format.
 

mne/gui/tests/test_kit2fiff_gui.py

@@ -4,6 +4,7 @@
 
 import os
 
+import pytest
 import numpy as np
 from numpy.testing import assert_allclose, assert_array_equal
 
@@ -123,7 +124,8 @@ def test_kit2fiff_gui(check_gui_ci, tmpdir):
         gui = GUI()
         gui.process_events()
 
-        ui, frame = mne.gui.kit2fiff()
+        with pytest.deprecated_call(match='mne-kit-gui'):
+            ui, frame = mne.gui.kit2fiff()
         assert not frame.model.can_save
         assert frame.model.stim_threshold == 1.
         frame.model.stim_threshold = 10.
@@ -134,7 +136,8 @@ def test_kit2fiff_gui(check_gui_ci, tmpdir):
         gui.process_events()
 
         # test setting persistence
-        ui, frame = mne.gui.kit2fiff()
+        with pytest.deprecated_call(match='mne-kit-gui'):
+            ui, frame = mne.gui.kit2fiff()
         assert frame.model.stim_threshold == 10.
         assert frame.model.stim_chs == 'save this!'
 

mne/utils/docs.py

@@ -3138,12 +3138,18 @@ def open_docs(kind=None, version=None):
 
 
 class deprecated:
-    """Mark a function or class as deprecated (decorator).
+    """Mark a function, class, or method as deprecated (decorator).
 
     Originally adapted from sklearn and
     http://wiki.python.org/moin/PythonDecoratorLibrary, then modified to make
     arguments populate properly following our verbose decorator methods based
     on externals.decorator.
+
+    Parameters
+    ----------
+    extra : str
+        Extra information beyond just saying the class/function/method
+        is deprecated.
     """
 
     def __init__(self, extra=''):  # noqa: D102
@@ -3156,6 +3162,11 @@ def __call__(self, obj):  # noqa: D105
         ----------
         obj : object
             Object to call.
+
+        Returns
+        -------
+        obj : object
+            The modified object.
         """
         if isinstance(obj, type):
             return self._decorate_class(obj)

mne/viz/backends/renderer.py

@@ -13,7 +13,7 @@
 import importlib
 
 from ._utils import VALID_3D_BACKENDS
-from ...utils import (logger, verbose, get_config, _check_option,
+from ...utils import (logger, verbose, get_config, _check_option, warn,
                       _require_version, fill_doc, _validate_type)
 
 MNE_3D_BACKEND = None
@@ -179,6 +179,10 @@ def _get_3d_backend():
             MNE_3D_BACKEND = _check_3d_backend_name(MNE_3D_BACKEND)
             _reload_backend(MNE_3D_BACKEND)
     MNE_3D_BACKEND = _check_3d_backend_name(MNE_3D_BACKEND)
+    if MNE_3D_BACKEND == 'mayavi':
+        warn('The Mayavi 3D backend is deprecated in 0.24 and will be removed '
+             'in the next version of MNE-Python. Use the pyvistaqt or '
+             'notebook backends instead', DeprecationWarning)
     return MNE_3D_BACKEND