API: Use scalings

doc/whats_new.rst

@@ -234,6 +234,8 @@ API
 
     - Add ``patterns=False`` parameter in :class:`mne.decoding.ReceptiveField`. Turn on to compute inverse model coefficients, by `Nicolas Barascud`_
 
+    - The ``scale``, ``scale_time``, and ``unit`` parameters have been deprecated in favor of ``scalings``, ``scalings_time``, and ``units`` in :func:`mne.viz.plot_evoked_topomap` and related functions, by `Eric Larson`_
+
 .. _changes_0_14:
 
 Version 0.14

examples/connectivity/plot_cwt_sensor_connectivity.py

@@ -1,6 +1,6 @@
 """
 ==============================================================
-Compute seed based time-frequency connectivity in sensor space
+Compute seed-based time-frequency connectivity in sensor space
 ==============================================================
 
 Computes the connectivity between a seed-gradiometer close to the visual cortex

examples/visualization/plot_topo_compare_conditions.py

@@ -3,11 +3,9 @@
 Compare evoked responses for different conditions
 =================================================
 
-In this example, an Epochs object for visual and
-auditory responses is created. Both conditions
-are then accessed by their respective names to
-create a sensor layout plot of the related
-evoked responses.
+In this example, an Epochs object for visual and auditory responses is created.
+Both conditions are then accessed by their respective names to create a sensor
+layout plot of the related evoked responses.
 
 """
 

mne/decoding/csp.py

@@ -290,11 +290,12 @@ def transform(self, X):
 
     def plot_patterns(self, info, components=None, ch_type=None, layout=None,
                       vmin=None, vmax=None, cmap='RdBu_r', sensors=True,
-                      colorbar=True, scale=None, unit='a.u.', res=64, size=1,
-                      cbar_fmt='%3.1f', name_format='CSP%01d', show=True,
-                      show_names=False, title=None, mask=None,
+                      colorbar=True, scalings=None, unit='a.u.', res=64,
+                      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, head_pos=None):
+                      image_interp='bilinear', average=None, head_pos=None,
+                      scale=None):
         """Plot topographic patterns of components.
 
         The patterns explain how the measured data was generated from the
@@ -346,9 +347,9 @@ def plot_patterns(self, info, components=None, ch_type=None, layout=None,
             a circle will be used (via .add_artist). Defaults to True.
         colorbar : bool
             Plot a colorbar.
-        scale : dict | float | None
-            Scale the data for plotting. If None, defaults to 1e6 for eeg, 1e13
-            for grad and 1e15 for mag.
+        scalings : dict | float | None
+            The scalings of the channel types to be applied for plotting.
+            If None, defaults to ``dict(eeg=1e6, grad=1e13, mag=1e15)``.
         unit : dict | str | None
             The unit of the channel type used for colorbar label. If
             scale is None the unit is automatically determined.
@@ -426,25 +427,23 @@ def plot_patterns(self, info, components=None, ch_type=None, layout=None,
         # create an evoked
         patterns = EvokedArray(self.patterns_.T, info, tmin=0)
         # the call plot_topomap
-        return patterns.plot_topomap(times=components, ch_type=ch_type,
-                                     layout=layout, vmin=vmin, vmax=vmax,
-                                     cmap=cmap, colorbar=colorbar, res=res,
-                                     cbar_fmt=cbar_fmt, sensors=sensors,
-                                     scale=scale, unit=unit, scale_time=1,
-                                     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, head_pos=head_pos)
+        return patterns.plot_topomap(
+            times=components, ch_type=ch_type, layout=layout,
+            vmin=vmin, vmax=vmax, cmap=cmap, colorbar=colorbar, res=res,
+            cbar_fmt=cbar_fmt, sensors=sensors,
+            scalings=scalings, unit=unit, scaling_time=1,
+            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, head_pos=head_pos, scale=scale)
 
     def plot_filters(self, info, components=None, ch_type=None, layout=None,
                      vmin=None, vmax=None, cmap='RdBu_r', sensors=True,
-                     colorbar=True, scale=None, unit='a.u.', res=64, size=1,
+                     colorbar=True, scalings=None, unit='a.u.', res=64, 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, head_pos=None):
+                     average=None, head_pos=None, scale=None):
         """Plot topographic filters of components.
 
         The filters are used to extract discriminant neural sources from
@@ -496,9 +495,9 @@ def plot_filters(self, info, components=None, ch_type=None, layout=None,
             a circle will be used (via .add_artist). Defaults to True.
         colorbar : bool
             Plot a colorbar.
-        scale : dict | float | None
-            Scale the data for plotting. If None, defaults to 1e6 for eeg, 1e13
-            for grad and 1e15 for mag.
+        scalings : dict | float | None
+            The scalings of the channel types to be applied for plotting.
+            If None, defaults to ``dict(eeg=1e6, grad=1e13, mag=1e15)``.
         unit : dict | str | None
             The unit of the channel type used for colorbar label. If
             scale is None the unit is automatically determined.
@@ -576,17 +575,15 @@ def plot_filters(self, info, components=None, ch_type=None, layout=None,
         # create an evoked
         filters = EvokedArray(self.filters_, info, tmin=0)
         # the call plot_topomap
-        return filters.plot_topomap(times=components, ch_type=ch_type,
-                                    layout=layout, vmin=vmin, vmax=vmax,
-                                    cmap=cmap, colorbar=colorbar, res=res,
-                                    cbar_fmt=cbar_fmt, sensors=sensors,
-                                    scale=scale, unit=unit, scale_time=1,
-                                    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, head_pos=head_pos)
+        return filters.plot_topomap(
+            times=components, ch_type=ch_type, layout=layout, vmin=vmin,
+            vmax=vmax, cmap=cmap, colorbar=colorbar, res=res,
+            cbar_fmt=cbar_fmt, sensors=sensors, scalings=scalings, unit=unit,
+            scaling_time=1, 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,
+            head_pos=head_pos, scale=scale)
 
 
 def _ajd_pham(X, eps=1e-6, max_iter=15):

mne/evoked.py

@@ -334,24 +334,21 @@ def plot_topo(self, layout=None, layout_scale=0.945, color=None,
     @copy_function_doc_to_method_doc(plot_evoked_topomap)
     def plot_topomap(self, times="auto", ch_type=None, layout=None, vmin=None,
                      vmax=None, cmap=None, sensors=True, colorbar=True,
-                     scale=None, scale_time=1e3, unit=None, res=64, size=1,
-                     cbar_fmt="%3.1f", time_format='%01d ms', proj=False,
-                     show=True, show_names=False, title=None, mask=None,
-                     mask_params=None, outlines='head', contours=6,
-                     image_interp='bilinear', average=None, head_pos=None,
-                     axes=None):
-        return plot_evoked_topomap(self, times=times, ch_type=ch_type,
-                                   layout=layout, vmin=vmin, vmax=vmax,
-                                   cmap=cmap, sensors=sensors,
-                                   colorbar=colorbar, scale=scale,
-                                   scale_time=scale_time, unit=unit, res=res,
-                                   proj=proj, size=size, cbar_fmt=cbar_fmt,
-                                   time_format=time_format, show=show,
-                                   show_names=show_names, title=title,
-                                   mask=mask, mask_params=mask_params,
-                                   outlines=outlines, contours=contours,
-                                   image_interp=image_interp, average=average,
-                                   head_pos=head_pos, axes=axes)
+                     scalings=None, scaling_time=1e3, unit=None, res=64,
+                     size=1, cbar_fmt="%3.1f", time_format='%01d ms',
+                     proj=False, show=True, show_names=False, title=None,
+                     mask=None, mask_params=None, outlines='head',
+                     contours=6, image_interp='bilinear', average=None,
+                     head_pos=None, axes=None, scale=None, scale_time=None):
+        return plot_evoked_topomap(
+            self, times=times, ch_type=ch_type, layout=layout, vmin=vmin,
+            vmax=vmax, cmap=cmap, sensors=sensors, colorbar=colorbar,
+            scalings=scalings, scaling_time=scaling_time, unit=unit, res=res,
+            size=size, cbar_fmt=cbar_fmt, 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,
+            head_pos=head_pos, axes=axes, scale=scale, scale_time=scale_time)
 
     @copy_function_doc_to_method_doc(plot_evoked_field)
     def plot_field(self, surf_maps, time=None, time_label='t = %0.0f ms',

mne/io/base.py

@@ -38,7 +38,7 @@
                      check_fname, _get_stim_channel,
                      logger, verbose, _time_mask, warn, SizeMixin,
                      copy_function_doc_to_method_doc,
-                     _check_preload)
+                     _check_preload, _scale_dep)
 from ..viz import plot_raw, plot_raw_psd, plot_raw_psd_topo
 from ..defaults import _handle_default
 from ..externals.six import string_types
@@ -59,8 +59,9 @@ def _get_check_picks(self, picks, picks_check):
                                  'in this object instance.')
         return picks
 
-    def to_data_frame(self, picks=None, index=None, scale_time=1e3,
-                      scalings=None, copy=True, start=None, stop=None):
+    def to_data_frame(self, picks=None, index=None, scaling_time=1e3,
+                      scalings=None, copy=True, start=None, stop=None,
+                      scale_time=None):
         """Export data in tabular structure as a pandas DataFrame.
 
         Columns and indices will depend on the object being converted.
@@ -78,7 +79,7 @@ def to_data_frame(self, picks=None, index=None, scale_time=1e3,
             Column to be used as index for the data. Valid string options
             are 'epoch', 'time' and 'condition'. If None, all three info
             columns will be included in the table as categorial data.
-        scale_time : float
+        scaling_time : float
             Scaling to be applied to time units.
         scalings : dict | None
             Scaling to be applied to the channels picked. If None, defaults to
@@ -105,6 +106,9 @@ def to_data_frame(self, picks=None, index=None, scale_time=1e3,
         from ..epochs import BaseEpochs
         from ..evoked import Evoked
         from ..source_estimate import _BaseSourceEstimate
+        scaling_time = _scale_dep(scaling_time, scale_time,
+                                  'scaling_time', 'scale_time')
+        del scale_time
 
         pd = _check_pandas_installed()
         mindex = list()
@@ -178,7 +182,7 @@ def to_data_frame(self, picks=None, index=None, scale_time=1e3,
                             'SourceEstimate. This is {0}'.format(type(self)))
 
         # Make sure that the time index is scaled correctly
-        times = np.round(times * scale_time)
+        times = np.round(times * scaling_time)
         mindex.append(('time', times))
 
         if index is not None:

mne/tests/test_docstring_parameters.py

@@ -2,6 +2,7 @@
 
 import inspect
 import os.path as op
+import re
 import sys
 from unittest import SkipTest
 import warnings
@@ -59,7 +60,7 @@ def get_name(func):
 _docstring_ignores = [
     'mne.io.Info',  # Parameters
     'mne.io.write',  # always ignore these
-    'mne.connectivity.effective.phase_slope_index',
+    # Deprecations
     'mne.connectivity.effective.phase_slope_index',
     'mne.connectivity.spectral.spectral_connectivity',
     'mne.decoding.time_frequency.TimeFrequency.__init__',
@@ -68,6 +69,11 @@ def get_name(func):
     'mne.time_frequency.multitaper.tfr_array_multitaper',
     'mne.time_frequency.tfr.tfr_array_morlet',
     'mne.time_frequency.tfr.tfr_morlet',
+    'mne.decoding.csp.CSP.plot_.*',
+    'mne.decoding.csp.SPoC.plot_.*',
+    'mne.*\.plot_topomap',
+    'mne.*\.to_data_frame',
+    'mne.viz.topomap.plot_evoked_topomap',
 ]
 
 _tab_ignores = [
@@ -105,7 +111,7 @@ def check_parameters_match(func, doc=None):
     if len(param_names) != len(args):
         bad = str(sorted(list(set(param_names) - set(args)) +
                          list(set(args) - set(param_names))))
-        if not any(d in name_ for d in _docstring_ignores) and \
+        if not any(re.match(d, name_) for d in _docstring_ignores) and \
                 'deprecation_wrapped' not in func.__code__.co_name:
             incorrect += [name_ + ' arg mismatch: ' + bad]
     else:

mne/utils.py

@@ -2647,6 +2647,14 @@ def open_docs(kind=None, version=None):
     webbrowser.open_new_tab('https://martinos.org/mne/%s/%s' % (version, kind))
 
 
+def _scale_dep(want, got, name_want, name_got):
+    if got is not None:
+        warn('%s is deprecated and will be removed in 0.16, use %s instead'
+             % (name_got, name_want), DeprecationWarning)
+        want = got
+    return want
+
+
 def _freqs_dep(freqs, frequencies, prefix=''):
     if frequencies is not None:
         freqs = frequencies

mne/viz/epochs.py

@@ -315,7 +315,7 @@ def _get_picks_and_types(picks, ch_types, group_by, combine):
             names.append(name)
     else:
         raise ValueError("If ``group_by`` is not None, it must be a dict "
-                         "or 'type', got " + type(group_by))
+                         "or 'type', got " + str(type(group_by)))
     return all_picks, all_ch_types, names  # all_picks is a list of lists
 
 

mne/viz/evoked.py

@@ -155,7 +155,7 @@ def _rgb(x, y, z):
     """Transform x, y, z values into RGB colors."""
     rgb = np.array([x, y, z]).T
     rgb -= rgb.min(0)
-    rgb /= rgb.max(0)
+    rgb /= np.maximum(rgb.max(0), 1e-16)  # avoid div by zero
     return rgb
 
 
@@ -533,8 +533,8 @@ def plot_evoked(evoked, picks=None, exclude='bads', unit=True, show=True,
         The units of the channel types used for axes lables. If None,
         defaults to `dict(eeg='uV', grad='fT/cm', mag='fT')`.
     scalings : dict | None
-        The scalings of the channel types to be applied for plotting. If None,`
-        defaults to `dict(eeg=1e6, grad=1e13, mag=1e15)`.
+        The scalings of the channel types to be applied for plotting. If None,
+        defaults to ``dict(eeg=1e6, grad=1e13, mag=1e15)``.
     titles : dict | None
         The titles associated with the channels. If None, defaults to
         `dict(eeg='EEG', grad='Gradiometers', mag='Magnetometers')`.

mne/viz/tests/test_3d.py

@@ -309,10 +309,10 @@ def test_stc_mpl():
         fig = stc.plot(subjects_dir=subjects_dir, time_unit='ms', views='dor',
                        hemi='lh', smoothing_steps=2, subject='sample',
                        backend='matplotlib', spacing='ico2', time_viewer=True)
-    time_viewer = fig.time_viewer
-    _fake_click(time_viewer, time_viewer.axes[0], (0.5, 0.5))  # change time
-    time_viewer.canvas.key_press_event('ctrl+right')
-    time_viewer.canvas.key_press_event('left')
+        time_viewer = fig.time_viewer
+        _fake_click(time_viewer, time_viewer.axes[0], (0.5, 0.5))  # change t
+        time_viewer.canvas.key_press_event('ctrl+right')
+        time_viewer.canvas.key_press_event('left')
     assert_raises(ValueError, stc.plot, subjects_dir=subjects_dir,
                   hemi='both', subject='sample', backend='matplotlib')
     assert_raises(ValueError, stc.plot, subjects_dir=subjects_dir,