[BUG, MRG] Replace image_interp with interpolation in topomap plot arguments

doc/changes/latest.inc

@@ -54,7 +54,7 @@ Enhancements
 
 - Add :func:`mne.preprocessing.compute_bridged_electrodes` to detect EEG electrodes with shared spatial sources due to a conductive medium connecting two or more electrodes, add :ref:`ex-eeg-bridging` for an example and :func:`mne.viz.plot_bridged_electrodes` to help visualize (:gh:`10571` by `Alex Rockhill`_)
 
-- Add ``'voronoi'`` as an option for the ``image_interp`` argument in :func:`mne.viz.plot_topomap` to plot a topomap without interpolation using a Voronoi parcelation (:gh:`10571` by `Alex Rockhill`_)
+- Add ``'nearest'`` as an option for the ``interpolation`` argument in :func:`mne.viz.plot_topomap` to plot a topomap without interpolation using a Voronoi parcelation (:gh:`10571` by `Alex Rockhill`_)
 
 - Add :func:`mne.preprocessing.interpolate_bridged_electrodes` to use the spatially smeared signal to get a better interpolation rather than dropping those channels (:gh:`10587` by `Alex Rockhill`_)
 
@@ -97,3 +97,5 @@ API and behavior changes
 - When creating BEM surfaces via :func:`mne.bem.make_watershed_bem` and :func:`mne.bem.make_flash_bem`, the ``copy`` parameter now defaults to ``True``. This means that instead of creating symbolic links inside the FreeSurfer subject's ``bem`` folder, we now create "actual" files. This should avoid troubles when sharing files across different operating systems and file systems (:gh:`10531` by `Richard Höchenberger`_)
 
 - The ordering of channels returned by :func:`mne.io.read_raw_nirx` is now ordered by channel name, rather than the order provided by the manufacturer. This enables consistent ordering of channels across different file types (:gh:`10555` by `Robert Luke`_)
+
+- :func:`mne.viz.plot_topomap`, :func:`mne.viz.plot_evoked_topomap`, :func:`mne.viz.plot_arrowmap`, :func:`mne.viz.plot_ica_components`, :meth:`mne.Covariance.plot_topomap`, :meth:`mne.Evoked.plot_topomap`, :meth:`mne.Evoked.animate_topomap`, :meth:`mne.decoding.CSP.plot_patterns`, :meth:`mne.Projection.plot_topomap` and :meth:`mne.preprocessing.ICA.plot_components` now use ``'interpolation'`` instead of ``'image_interp'``. The interpolation previously used a cubic interpolation but now allows ``'linear'`` and ``'nearest'``. There was a subsequent matplotlib plotting interpolation controlled by ``'image_interp'`` that has been removed as a parameter but can be set afterward using ``im.set_interpolation`` (:gh:`10617` by `Alex Rockhill`_)

examples/preprocessing/eeg_bridging.py

@@ -256,7 +256,7 @@
 
 raw = raw_data[2].copy()
 
-# pick two channels to simulate being bridged
+# pick two channels to simulate a bridge
 idx0, idx1 = 9, 10
 ch0, ch1 = raw.ch_names[idx0], raw.ch_names[idx1]
 bridged_idx_simulated = [(idx0, idx1)]

mne/cov.py

@@ -10,7 +10,8 @@
 
 import numpy as np
 
-from .defaults import _EXTRAPOLATE_DEFAULT, _BORDER_DEFAULT, DEFAULTS
+from .defaults import (_INTERPOLATION_DEFAULT, _EXTRAPOLATE_DEFAULT,
+                       _BORDER_DEFAULT, DEFAULTS)
 from .io.write import start_and_end_file
 from .io.proj import (make_projector, _proj_equal, activate_proj,
                       _check_projs, _needs_eeg_average_ref_proj,
@@ -257,8 +258,9 @@ def plot_topomap(self, info, ch_type=None, vmin=None,
                      size=1, cbar_fmt="%3.1f",
                      proj=False, show=True, show_names=False, title=None,
                      mask=None, mask_params=None, outlines='head',
-                     contours=6, image_interp='bilinear',
-                     axes=None, extrapolate=_EXTRAPOLATE_DEFAULT, sphere=None,
+                     contours=6, interpolation=_INTERPOLATION_DEFAULT,
+                     image_interp=None, axes=None,
+                     extrapolate=_EXTRAPOLATE_DEFAULT, sphere=None,
                      border=_BORDER_DEFAULT,
                      noise_cov=None, verbose=None):
         """Plot a topomap of the covariance diagonal.
@@ -284,6 +286,7 @@ def plot_topomap(self, info, ch_type=None, vmin=None,
         %(mask_params_topomap)s
         %(outlines_topomap)s
         %(contours_topomap)s
+        %(interpolation_topomap)s
         %(image_interp_topomap)s
         %(axes_topomap)s
         %(extrapolate_topomap)s
@@ -324,7 +327,8 @@ def plot_topomap(self, info, ch_type=None, vmin=None,
             units=units, res=res, size=size, cbar_fmt=cbar_fmt,
             proj=proj, show=show, show_names=show_names, title=title,
             mask=mask, mask_params=mask_params, outlines=outlines,
-            contours=contours, image_interp=image_interp, axes=axes,
+            contours=contours, interpolation=interpolation,
+            image_interp=image_interp, axes=axes,
             extrapolate=extrapolate, sphere=sphere, border=border,
             time_format='')
 

mne/decoding/csp.py

@@ -14,6 +14,7 @@
 from .base import BaseEstimator
 from .mixin import TransformerMixin
 from ..cov import _regularized_covariance
+from ..defaults import _INTERPOLATION_DEFAULT
 from ..fixes import pinv
 from ..utils import fill_doc, _check_option, _validate_type, copy_doc
 
@@ -242,8 +243,8 @@ def plot_patterns(self, info, components=None, ch_type=None,
                       size=1, cbar_fmt='%3.1f', name_format='CSP%01d',
                       show=True, show_names=False, title=None, mask=None,
                       mask_params=None, outlines='head', contours=6,
-                      image_interp='bilinear', average=None,
-                      sphere=None):
+                      interpolation=_INTERPOLATION_DEFAULT,
+                      image_interp=None, average=None, sphere=None):
         """Plot topographic patterns of components.
 
         The patterns explain how the measured data was generated from the
@@ -321,9 +322,8 @@ def plot_patterns(self, info, components=None, ch_type=None,
             suitable values for the contour thresholds (may sometimes be
             inaccurate, use array for accuracy). If an array, the values
             represent the levels for the contours. Defaults to 6.
-        image_interp : str
-            The image interpolation to be used.
-            All matplotlib options are accepted.
+        %(interpolation_topomap)s
+        %(image_interp_topomap)s
         average : float | None
             The time window around a given time to be used for averaging
             (seconds). For example, 0.01 would translate into window that
@@ -354,8 +354,9 @@ def plot_patterns(self, info, components=None, ch_type=None,
             scalings=scalings, units=units, time_unit='s',
             time_format=name_format, size=size, show_names=show_names,
             title=title, mask_params=mask_params, mask=mask, outlines=outlines,
-            contours=contours, image_interp=image_interp, show=show,
-            average=average, sphere=sphere)
+            contours=contours, interpolation=interpolation,
+            image_interp=image_interp, show=show, average=average,
+            sphere=sphere)
 
     @fill_doc
     def plot_filters(self, info, components=None, ch_type=None,
@@ -364,7 +365,8 @@ def plot_filters(self, info, components=None, ch_type=None,
                      size=1, cbar_fmt='%3.1f', name_format='CSP%01d',
                      show=True, show_names=False, title=None, mask=None,
                      mask_params=None, outlines='head', contours=6,
-                     image_interp='bilinear', average=None):
+                     interpolation=_INTERPOLATION_DEFAULT, image_interp=None,
+                     average=None):
         """Plot topographic filters of components.
 
         The filters are used to extract discriminant neural sources from
@@ -449,9 +451,8 @@ def plot_filters(self, info, components=None, ch_type=None,
             suitable values for the contour thresholds (may sometimes be
             inaccurate, use array for accuracy). If an array, the values
             represent the levels for the contours. Defaults to 6.
-        image_interp : str
-            The image interpolation to be used.
-            All matplotlib options are accepted.
+        %(interpolation_topomap)s
+        %(image_interp_topomap)s
         average : float | None
             The time window around a given time to be used for averaging
             (seconds). For example, 0.01 would translate into window that
@@ -481,7 +482,8 @@ def plot_filters(self, info, components=None, ch_type=None,
             time_unit='s', time_format=name_format, size=size,
             show_names=show_names, title=title, mask_params=mask_params,
             mask=mask, outlines=outlines, contours=contours,
-            image_interp=image_interp, show=show, average=average)
+            interpolation=interpolation, image_interp=image_interp,
+            show=show, average=average)
 
     def _compute_covariance_matrices(self, X, y):
         _, n_channels, _ = X.shape

mne/defaults.py

@@ -191,4 +191,5 @@ def _handle_default(k, v=None):
 
 HEAD_SIZE_DEFAULT = 0.095  # in [m]
 _BORDER_DEFAULT = 'mean'
+_INTERPOLATION_DEFAULT = 'cubic'
 _EXTRAPOLATE_DEFAULT = 'auto'

mne/evoked.py

@@ -15,7 +15,8 @@
 from .channels.channels import (UpdateChannelsMixin,
                                 SetChannelsMixin, InterpolationMixin)
 from .channels.layout import _merge_ch_data, _pair_grad_sensors
-from .defaults import _EXTRAPOLATE_DEFAULT, _BORDER_DEFAULT
+from .defaults import (_INTERPOLATION_DEFAULT, _EXTRAPOLATE_DEFAULT,
+                       _BORDER_DEFAULT)
 from .filter import detrend, FilterMixin, _check_fun
 from .utils import (check_fname, logger, verbose, _time_mask, warn, sizeof_fmt,
                     SizeMixin, copy_function_doc_to_method_doc, _validate_type,
@@ -484,8 +485,9 @@ def plot_topomap(self, times="auto", ch_type=None, vmin=None,
                      time_unit='s', time_format=None,
                      proj=False, show=True, show_names=False, title=None,
                      mask=None, mask_params=None, outlines='head',
-                     contours=6, image_interp='bilinear', average=None,
-                     axes=None, extrapolate=_EXTRAPOLATE_DEFAULT, sphere=None,
+                     contours=6, interpolation=_INTERPOLATION_DEFAULT,
+                     image_interp=None, average=None, axes=None,
+                     extrapolate=_EXTRAPOLATE_DEFAULT, sphere=None,
                      border=_BORDER_DEFAULT, nrows=1, ncols='auto'):
         return plot_evoked_topomap(
             self, times=times, ch_type=ch_type, vmin=vmin,
@@ -495,9 +497,9 @@ def plot_topomap(self, times="auto", ch_type=None, vmin=None,
             time_format=time_format, proj=proj, show=show,
             show_names=show_names, title=title, mask=mask,
             mask_params=mask_params, outlines=outlines, contours=contours,
-            image_interp=image_interp, average=average,
-            axes=axes, extrapolate=extrapolate, sphere=sphere, border=border,
-            nrows=nrows, ncols=ncols)
+            interpolation=interpolation, image_interp=image_interp,
+            average=average, axes=axes, extrapolate=extrapolate,
+            sphere=sphere, border=border, nrows=nrows, ncols=ncols)
 
     @copy_function_doc_to_method_doc(plot_evoked_field)
     def plot_field(self, surf_maps, time=None, time_label='t = %0.0f ms',
@@ -526,7 +528,8 @@ def plot_joint(self, times="peaks", title='', picks=None,
     @fill_doc
     def animate_topomap(self, ch_type=None, times=None, frame_rate=None,
                         butterfly=False, blit=True, show=True, time_unit='s',
-                        sphere=None, *, extrapolate=_EXTRAPOLATE_DEFAULT,
+                        sphere=None, *, interpolation=_INTERPOLATION_DEFAULT,
+                        image_interp=None, extrapolate=_EXTRAPOLATE_DEFAULT,
                         verbose=None):
         """Make animation of evoked data as topomap timeseries.
 
@@ -564,6 +567,8 @@ def animate_topomap(self, ch_type=None, times=None, frame_rate=None,
 
             .. versionadded:: 0.16
         %(sphere_topomap_auto)s
+        %(interpolation_topomap)s
+        %(image_interp_topomap)s
         %(extrapolate_topomap)s
 
             .. versionadded:: 0.22
@@ -580,10 +585,17 @@ def animate_topomap(self, ch_type=None, times=None, frame_rate=None,
         -----
         .. versionadded:: 0.12.0
         """
+        if image_interp is not None:
+            # use default cubic if default bilinear is passed
+            interpolation = \
+                'cubic' if image_interp == 'bilinear' else image_interp
+            warn('`image_interp` has been deprecated and has been replaced '
+                 'with `interpolation` as of version 1.1', DeprecationWarning)
         return _topomap_animation(
             self, ch_type=ch_type, times=times, frame_rate=frame_rate,
             butterfly=butterfly, blit=blit, show=show, time_unit=time_unit,
-            sphere=sphere, extrapolate=extrapolate, verbose=verbose)
+            sphere=sphere, interpolation=interpolation,
+            extrapolate=extrapolate, verbose=verbose)
 
     def as_type(self, ch_type='grad', mode='fast'):
         """Compute virtual evoked using interpolated fields.

mne/io/proj.py

@@ -16,7 +16,8 @@
 from .tree import dir_tree_find
 from .write import (write_int, write_float, write_string, write_name_list,
                     write_float_matrix, end_block, start_block)
-from ..defaults import _BORDER_DEFAULT, _EXTRAPOLATE_DEFAULT
+from ..defaults import (_INTERPOLATION_DEFAULT, _BORDER_DEFAULT,
+                        _EXTRAPOLATE_DEFAULT)
 from ..utils import logger, verbose, warn, fill_doc, _validate_type
 
 
@@ -72,7 +73,8 @@ def __deepcopy__(self, memodict):
     @fill_doc
     def plot_topomap(self, info, cmap=None, sensors=True,
                      colorbar=False, res=64, size=1, show=True,
-                     outlines='head', contours=6, image_interp='bilinear',
+                     outlines='head', contours=6,
+                     interpolation=_INTERPOLATION_DEFAULT, image_interp=None,
                      axes=None, vlim=(None, None), sphere=None,
                      border=_BORDER_DEFAULT):
         """Plot topographic maps of SSP projections.
@@ -94,10 +96,11 @@ def plot_topomap(self, info, cmap=None, sensors=True,
         .. versionadded:: 0.15.0
         """  # noqa: E501
         from ..viz.topomap import plot_projs_topomap
-        return plot_projs_topomap(self, info, cmap, sensors, colorbar,
-                                  res, size, show, outlines,
-                                  contours, image_interp, axes, vlim,
-                                  sphere=sphere, border=border)
+        return plot_projs_topomap(
+            self, info, cmap, sensors, colorbar=colorbar, res=res, size=size,
+            show=show, outlines=outlines, contours=contours,
+            interpolation=interpolation, image_interp=image_interp,
+            axes=axes, vlim=vlim, sphere=sphere, border=border)
 
 
 class ProjMixin(object):
@@ -288,9 +291,9 @@ def del_proj(self, idx='all'):
     def plot_projs_topomap(self, ch_type=None, cmap=None,
                            sensors=True, colorbar=False, res=64, size=1,
                            show=True, outlines='head', contours=6,
-                           image_interp='bilinear', axes=None,
-                           vlim=(None, None), sphere=None,
-                           extrapolate=_EXTRAPOLATE_DEFAULT,
+                           interpolation=_INTERPOLATION_DEFAULT,
+                           image_interp=None, axes=None, vlim=(None, None),
+                           sphere=None, extrapolate=_EXTRAPOLATE_DEFAULT,
                            border=_BORDER_DEFAULT):
         """Plot SSP vector.
 
@@ -303,6 +306,8 @@ def plot_projs_topomap(self, ch_type=None, cmap=None,
             ch_types is provided, it will return multiple figures.
         %(proj_topomap_kwargs)s
         %(sphere_topomap_auto)s
+        %(interpolation_topomap)s
+        %(image_interp_topomap)s
         %(extrapolate_topomap)s
 
             .. versionadded:: 0.20
@@ -319,6 +324,7 @@ def plot_projs_topomap(self, ch_type=None, cmap=None,
                                      sensors=sensors, colorbar=colorbar,
                                      res=res, size=size, show=show,
                                      outlines=outlines, contours=contours,
+                                     interpolation=interpolation,
                                      image_interp=image_interp, axes=axes,
                                      vlim=vlim, sphere=sphere,
                                      extrapolate=extrapolate, border=border)

mne/preprocessing/ica.py

@@ -26,6 +26,7 @@
 
 from ..cov import compute_whitener
 from .. import Covariance, Evoked
+from ..defaults import _INTERPOLATION_DEFAULT
 from ..io.pick import (pick_types, pick_channels, pick_info,
                        _picks_to_idx, _get_channel_types, _DATA_CH_TYPES_SPLIT)
 from ..io.proj import make_projector
@@ -2027,15 +2028,16 @@ def copy(self):
     def plot_components(self, picks=None, ch_type=None, res=64,
                         vmin=None, vmax=None, cmap='RdBu_r', sensors=True,
                         colorbar=False, title=None, show=True, outlines='head',
-                        contours=6, image_interp='bilinear',
-                        inst=None, plot_std=True, topomap_args=None,
-                        image_args=None, psd_args=None, reject='auto',
-                        sphere=None, verbose=None):
+                        contours=6, interpolation=_INTERPOLATION_DEFAULT,
+                        image_interp=None, inst=None, plot_std=True,
+                        topomap_args=None, image_args=None, psd_args=None,
+                        reject='auto', sphere=None, verbose=None):
         return plot_ica_components(self, picks=picks, ch_type=ch_type,
                                    res=res, vmin=vmin,
                                    vmax=vmax, cmap=cmap, sensors=sensors,
                                    colorbar=colorbar, title=title, show=show,
                                    outlines=outlines, contours=contours,
+                                   interpolation=interpolation,
                                    image_interp=image_interp,
                                    inst=inst, plot_std=plot_std,
                                    topomap_args=topomap_args,

mne/utils/docs.py

@@ -1419,8 +1419,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 
 docdict['image_interp_topomap'] = """
 image_interp : str
-    The image interpolation to be used. All matplotlib options are
-    accepted as well as ``'voronoi'``.
+    Deprecated, please use the ``'interpolation'`` parameter instead.
 """
 
 docdict['include_tmax'] = """
@@ -1513,6 +1512,14 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
     or 'cubic'.
 """
 
+docdict['interpolation_topomap'] = """
+interpolation : str
+    The image interpolation to be used. Options are ``'cubic'`` (default)
+    to use :class:`scipy.interpolate.CloughTocher2DInterpolator`,
+    ``'nearest'`` to use :class:`scipy.spatial.Voronoi` or
+    ``'linear'`` to use :class:`scipy.interpolate.LinearNDInterpolator`.
+"""
+
 docdict['inversion_bf'] = """
 inversion : 'single' | 'matrix'
     This determines how the beamformer deals with source spaces in "free"
@@ -2355,9 +2362,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
     values for the contour thresholds (may sometimes be inaccurate, use
     array for accuracy). If an array, the values represent the levels for
     the contours. Defaults to 6.
-image_interp : str
-    The image interpolation to be used. All matplotlib options are
-    accepted.
+""" + docdict['interpolation_topomap'] + docdict['image_interp_topomap'] + """
 axes : instance of Axes | list | None
     The axes to plot to. If list, the list must be a list of Axes of
     the same length as the number of projectors. If instance of Axes,