Repository: mne-tools/mne-python

Issue:
Epochs should have plot_image as method
Currently, you have to use `mne.viz.plot_epochs_image` for plotting. It would be convenient to have it as a method like the other plotting functions.



Discussion:
+1

@Famguy , smth for you? You already know the function.


Resolving patch:
diff --git a/mne/epochs.py b/mne/epochs.py
--- a/mne/epochs.py
+++ b/mne/epochs.py
@@ -38,7 +38,8 @@
 from .filter import resample, detrend, FilterMixin
 from .event import _read_events_fif
 from .fixes import in1d, _get_args
-from .viz import plot_epochs, plot_epochs_psd, plot_epochs_psd_topomap
+from .viz import (plot_epochs, plot_epochs_psd, plot_epochs_psd_topomap,
+                  plot_epochs_image)
 from .utils import (check_fname, logger, verbose, _check_type_picks,
                     _time_mask, check_random_state, object_hash, warn)
 from .externals.six import iteritems, string_types
@@ -1084,6 +1085,68 @@ def plot_drop_log(self, threshold=0, n_max_plot=20, subject='Unknown',
                              color=color, width=width, ignore=ignore,
                              show=show)
 
+    def plot_image(self, picks=None, sigma=0., vmin=None,
+                   vmax=None, colorbar=True, order=None, show=True,
+                   units=None, scalings=None, cmap='RdBu_r',
+                   fig=None, overlay_times=None):
+        """Plot Event Related Potential / Fields image
+
+        Parameters
+        ----------
+        picks : int | array-like of int | None
+            The indices of the channels to consider. If None, the first
+            five good channels are plotted.
+        sigma : float
+            The standard deviation of the Gaussian smoothing to apply along
+            the epoch axis to apply in the image. If 0., no smoothing is
+            applied.
+        vmin : float
+            The min value in the image. The unit is uV for EEG channels,
+            fT for magnetometers and fT/cm for gradiometers.
+        vmax : float
+            The max value in the image. The unit is uV for EEG channels,
+            fT for magnetometers and fT/cm for gradiometers.
+        colorbar : bool
+            Display or not a colorbar.
+        order : None | array of int | callable
+            If not None, order is used to reorder the epochs on the y-axis
+            of the image. If it's an array of int it should be of length
+            the number of good epochs. If it's a callable the arguments
+            passed are the times vector and the data as 2d array
+            (data.shape[1] == len(times).
+        show : bool
+            Show figure if True.
+        units : dict | None
+            The units of the channel types used for axes lables. If None,
+            defaults to `units=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 `scalings=dict(eeg=1e6, grad=1e13, mag=1e15,
+            eog=1e6)`.
+        cmap : matplotlib colormap
+            Colormap.
+        fig : matplotlib figure | None
+            Figure instance to draw the image to. Figure must contain two
+            axes for drawing the single trials and evoked responses. If
+            None a new figure is created. Defaults to None.
+        overlay_times : array-like, shape (n_epochs,) | None
+            If not None the parameter is interpreted as time instants in
+            seconds and is added to the image. It is typically useful to
+            display reaction times. Note that it is defined with respect
+            to the order of epochs such that overlay_times[0] corresponds
+            to epochs[0].
+
+        Returns
+        -------
+        figs : list of matplotlib figures
+            One figure per channel displayed.
+        """
+        return plot_epochs_image(self, picks=picks, sigma=sigma, vmin=vmin,
+                                 vmax=vmax, colorbar=colorbar, order=order,
+                                 show=show, units=units, scalings=scalings,
+                                 cmap=cmap, fig=fig,
+                                 overlay_times=overlay_times)
+
     @verbose
     def drop_epochs(self, indices, reason='USER', verbose=None):
         """Drop epochs based on indices or boolean mask
diff --git a/mne/viz/epochs.py b/mne/viz/epochs.py
--- a/mne/viz/epochs.py
+++ b/mne/viz/epochs.py
@@ -34,7 +34,7 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
     Parameters
     ----------
     epochs : instance of Epochs
-        The epochs
+        The epochs.
     picks : int | array-like of int | None
         The indices of the channels to consider. If None, the first
         five good channels are plotted.
@@ -43,18 +43,18 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
         the epoch axis to apply in the image. If 0., no smoothing is applied.
     vmin : float
         The min value in the image. The unit is uV for EEG channels,
-        fT for magnetometers and fT/cm for gradiometers
+        fT for magnetometers and fT/cm for gradiometers.
     vmax : float
         The max value in the image. The unit is uV for EEG channels,
-        fT for magnetometers and fT/cm for gradiometers
+        fT for magnetometers and fT/cm for gradiometers.
     colorbar : bool
-        Display or not a colorbar
+        Display or not a colorbar.
     order : None | array of int | callable
         If not None, order is used to reorder the epochs on the y-axis
         of the image. If it's an array of int it should be of length
         the number of good epochs. If it's a callable the arguments
         passed are the times vector and the data as 2d array
-        (data.shape[1] == len(times)
+        (data.shape[1] == len(times).
     show : bool
         Show figure if True.
     units : dict | None
@@ -63,7 +63,7 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
     scalings : dict | None
         The scalings of the channel types to be applied for plotting.
         If None, defaults to `scalings=dict(eeg=1e6, grad=1e13, mag=1e15,
-        eog=1e6)`
+        eog=1e6)`.
     cmap : matplotlib colormap
         Colormap.
     fig : matplotlib figure | None
@@ -78,8 +78,8 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
 
     Returns
     -------
-    figs : the list of matplotlib figures
-        One figure per channel displayed
+    figs : lists of matplotlib figures
+        One figure per channel displayed.
     """
     from scipy import ndimage
     units = _handle_default('units', units)


Test patch:
diff --git a/mne/viz/tests/test_epochs.py b/mne/viz/tests/test_epochs.py
--- a/mne/viz/tests/test_epochs.py
+++ b/mne/viz/tests/test_epochs.py
@@ -18,7 +18,7 @@
 from mne.utils import run_tests_if_main, requires_version
 from mne.channels import read_layout
 
-from mne.viz import plot_drop_log, plot_epochs_image
+from mne.viz import plot_drop_log
 from mne.viz.utils import _fake_click
 
 # Set our plotters to test mode
@@ -130,16 +130,16 @@ def test_plot_epochs_image():
     """
     import matplotlib.pyplot as plt
     epochs = _get_epochs()
-    plot_epochs_image(epochs, picks=[1, 2])
+    epochs.plot_image(picks=[1, 2])
     overlay_times = [0.1]
-    plot_epochs_image(epochs, order=[0], overlay_times=overlay_times)
-    plot_epochs_image(epochs, overlay_times=overlay_times)
-    assert_raises(ValueError, plot_epochs_image, epochs,
+    epochs.plot_image(order=[0], overlay_times=overlay_times)
+    epochs.plot_image(overlay_times=overlay_times)
+    assert_raises(ValueError, epochs.plot_image,
                   overlay_times=[0.1, 0.2])
-    assert_raises(ValueError, plot_epochs_image, epochs,
+    assert_raises(ValueError, epochs.plot_image,
                   order=[0, 1])
     with warnings.catch_warnings(record=True) as w:
-        plot_epochs_image(epochs, overlay_times=[1.1])
+        epochs.plot_image(overlay_times=[1.1])
         warnings.simplefilter('always')
     assert_equal(len(w), 1)