[MRG] plot_ica_properties

doc/whats_new.rst

@@ -23,6 +23,8 @@ Changelog
 
     - Add label center of mass function :func:`mne.Label.center_of_mass` by `Eric Larson`_
 
+    - Added :func:`mne.viz.ica.plot_ica_properties` that allows ploting of independent component properties similar to ``pop_prop`` in EEGLAB. Also :class:`mne.preprocessing.ica.ICA` has :func:`mne.preprocessing.ica.ICA.plot_properties` method now. Added by `Mikołaj Magnuski`_
+
 BUG
 ~~~
 
@@ -59,6 +61,8 @@ API
 
     - :func:`mne.concatenate_epochs` and :func:`mne.compute_covariance` now check to see if all :class:`Epochs` instances have the same MEG-to-Head transformation, and errors by default if they do not by `Eric Larson`_
 
+    - Added option to pass a list of axes to :func:`mne.viz.epochs.plot_epochs_image` by `Mikołaj Magnuski`_
+
 .. _changes_0_12:
 
 Version 0.12
@@ -1603,3 +1607,5 @@ of commits):
 .. _Pablo-Arias: https://github.com/Pablo-Arias
 
 .. _Alexander Rudiuk: https://github.com/ARudiuk
+
+.. _Mikołaj Magnuski: https://github.com/mmagnuski

examples/preprocessing/plot_run_ica.py

@@ -44,3 +44,4 @@
 ecg_inds, scores = ica.find_bads_ecg(ecg_epochs)
 
 ica.plot_components(ecg_inds)
+ica.plot_properties(epochs, picks=ecg_inds)

mne/epochs.py

@@ -37,7 +37,7 @@
 from .channels.channels import (ContainsMixin, UpdateChannelsMixin,
                                 SetChannelsMixin, InterpolationMixin)
 from .filter import resample, detrend, FilterMixin
-from .event import _read_events_fif
+from .event import _read_events_fif, make_fixed_length_events
 from .fixes import in1d, _get_args
 from .viz import (plot_epochs, plot_epochs_psd, plot_epochs_psd_topomap,
                   plot_epochs_image, plot_topo_image_epochs)
@@ -3112,3 +3112,29 @@ def average_movements(epochs, head_pos=None, orig_sfreq=None, picks=None,
     _remove_meg_projs(evoked)  # remove MEG projectors, they won't apply now
     logger.info('Created Evoked dataset from %s epochs' % (count,))
     return (evoked, mapping) if return_mapping else evoked
+
+
+@verbose
+def _segment_raw(raw, segment_length=1., verbose=None, **kwargs):
+    """Divide continuous raw data into equal-sized
+    consecutive epochs.
+
+    Parameters
+    ----------
+    raw : instance of Raw
+        Raw data to divide into segments.
+    segment_length : float
+        Length of each segment in seconds. Defaults to 1.
+    verbose: bool
+        Whether to report what is being done by printing text.
+    **kwargs
+        Any additional keyword arguments are passed to ``Epochs`` constructor.
+
+    Returns
+    -------
+    epochs : instance of ``Epochs``
+        Segmented data.
+    """
+    events = make_fixed_length_events(raw, 1, duration=segment_length)
+    return Epochs(raw, events, event_id=[1], tmin=0., tmax=segment_length,
+                  verbose=verbose, baseline=None, **kwargs)

mne/event.py

@@ -765,6 +765,15 @@ def make_fixed_length_events(raw, id, start=0, stop=None, duration=1.,
     new_events : array
         The new events.
     """
+    from .io.base import _BaseRaw
+    if not isinstance(raw, _BaseRaw):
+        raise ValueError('Input data must be an instance of Raw, got'
+                         ' %s instead.' % (type(raw)))
+    if not isinstance(id, int):
+        raise ValueError('id must be an integer')
+    if not isinstance(duration, (int, float)):
+        raise ValueError('duration must be an integer of a float, '
+                         'got %s instead.' % (type(duration)))
     start = raw.time_as_index(start)[0]
     if stop is not None:
         stop = raw.time_as_index(stop)[0]
@@ -775,8 +784,6 @@ def make_fixed_length_events(raw, id, start=0, stop=None, duration=1.,
         stop = min([stop + raw.first_samp, raw.last_samp + 1])
     else:
         stop = min([stop, len(raw.times)])
-    if not isinstance(id, int):
-        raise ValueError('id must be an integer')
     # Make sure we don't go out the end of the file:
     stop -= int(np.ceil(raw.info['sfreq'] * duration))
     # This should be inclusive due to how we generally use start and stop...

mne/preprocessing/ica.py

@@ -35,6 +35,7 @@
 from ..epochs import _BaseEpochs
 from ..viz import (plot_ica_components, plot_ica_scores,
                    plot_ica_sources, plot_ica_overlay)
+from ..viz.ica import plot_ica_properties
 from ..viz.utils import (_prepare_trellis, tight_layout, plt_show,
                          _setup_vmin_vmax)
 from ..viz.topomap import (_prepare_topo_plot, _check_outlines,
@@ -1400,6 +1401,58 @@ def plot_components(self, picks=None, ch_type=None, res=64, layout=None,
                                    image_interp=image_interp,
                                    head_pos=head_pos)
 
+    def plot_properties(self, inst, picks=None, axes=None, dB=True,
+                        plot_std=True, topomap_args=None, image_args=None,
+                        psd_args=None, figsize=None, show=True):
+        """Display component properties: topography, epochs image, ERP,
+        power spectrum and epoch variance.
+
+        Parameters
+        ----------
+        inst: instance of Epochs or Raw
+            The data to use in plotting properties.
+        picks : int | array-like of int | None
+            The components to be displayed. If None, plot will show the first
+            five sources. If more than one components were chosen in the picks,
+            each one will be plotted in a separate figure. Defaults to None.
+        axes: list of matplotlib axes | None
+            List of five matplotlib axes to use in plotting: [topo_axis,
+            image_axis, erp_axis, spectrum_axis, variance_axis]. If None a new
+            figure with relevant axes is created. Defaults to None.
+        dB: bool
+            Whether to plot spectrum in dB. Defaults to True.
+        plot_std: bool | float
+            Whether to plot standard deviation in ERP/ERF and spectrum plots.
+            Defaults to True, which plots one standard deviation above/below.
+            If set to float allows to control how many standard deviations are
+            plotted. For example 2.5 will plot 2.5 standard deviation
+            above/below.
+        topomap_args : dict | None
+            Dictionary of arguments to ``plot_topomap``. If None, doesn't pass
+            any additional arguments. Defaults to None.
+        image_args : dict | None
+            Dictionary of arguments to ``plot_epochs_image``. If None, doesn't
+            pass any additional arguments. Defaults to None.
+        psd_args : dict | None
+            Dictionary of arguments to ``psd_multitaper``. If None, doesn't
+            pass any additional arguments. Defaults to None.
+        figsize : array-like of size (2,) | None
+            Allows to control size of the figure. If None the figure size
+            defauls to [7., 6.].
+        show : bool
+            Show figure if True.
+
+        Returns
+        -------
+        fig : list
+            List of matplotlib figures.
+        """
+        return plot_ica_properties(inst, self, picks=picks, axes=axes,
+                                   dB=dB, plot_std=plot_std,
+                                   topomap_args=topomap_args,
+                                   image_args=image_args, psd_args=psd_args,
+                                   figsize=figsize, show=show)
+
     def plot_sources(self, inst, picks=None, exclude=None, start=None,
                      stop=None, title=None, show=True, block=False):
         """Plot estimated latent sources given the unmixing matrix.

mne/tests/test_event.py

@@ -353,6 +353,11 @@ def test_make_fixed_length_events():
     # With bad limits (no resulting events)
     assert_raises(ValueError, make_fixed_length_events, raw, 1,
                   tmin, tmax - 1e-3, duration)
+    # not raw, bad id or duration
+    assert_raises(ValueError, make_fixed_length_events, raw, 2.3)
+    assert_raises(ValueError, make_fixed_length_events, 'not raw', 2)
+    assert_raises(ValueError, make_fixed_length_events, raw, 23, tmin, tmax,
+                  'abc')
 
 
 def test_define_events():

mne/viz/epochs.py

@@ -29,7 +29,7 @@
 def plot_epochs_image(epochs, 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):
+                      fig=None, axes=None, overlay_times=None):
     """Plot Event Related Potential / Fields image
 
     Parameters
@@ -71,6 +71,11 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=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.
+    axes : list of matplotlib axes | None
+        List of axes instances to draw the image, erp and colorbar to.
+        Must be of length three if colorbar is True (with the last list element
+        being the colorbar axes) or two if colorbar is False. If both fig and
+        axes are passed an error is raised. 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
@@ -95,8 +100,20 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
         raise ValueError('Scalings and units must have the same keys.')
 
     picks = np.atleast_1d(picks)
-    if fig is not None and len(picks) > 1:
+    if (fig is not None or axes is not None) and len(picks) > 1:
         raise ValueError('Only single pick can be drawn to a figure.')
+    if axes is not None:
+        if fig is not None:
+            raise ValueError('Both figure and axes were passed, please'
+                             'decide between the two.')
+        from .utils import _validate_if_list_of_axes
+        oblig_len = 3 if colorbar else 2
+        _validate_if_list_of_axes(axes, obligatory_len=oblig_len)
+        ax1, ax2 = axes[:2]
+        # if axes were passed - we ignore fig param and get figure from axes
+        fig = ax1.get_figure()
+        if colorbar:
+            ax3 = axes[-1]
     evoked = epochs.average(picks)
     data = epochs.get_data()[:, picks, :]
     scale_vmin = True if vmin is None else False
@@ -154,7 +171,11 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
             this_data = ndimage.gaussian_filter1d(this_data, sigma=sigma,
                                                   axis=0)
         plt.figure(this_fig.number)
-        ax1 = plt.subplot2grid((3, 10), (0, 0), colspan=9, rowspan=2)
+        if axes is None:
+            ax1 = plt.subplot2grid((3, 10), (0, 0), colspan=9, rowspan=2)
+            ax2 = plt.subplot2grid((3, 10), (2, 0), colspan=9, rowspan=1)
+            if colorbar:
+                ax3 = plt.subplot2grid((3, 10), (0, 9), colspan=1, rowspan=3)
         if scale_vmin:
             vmin *= scalings[ch_type]
         if scale_vmax:
@@ -167,9 +188,6 @@ def plot_epochs_image(epochs, picks=None, sigma=0., vmin=None,
         if this_overlay_times is not None:
             plt.plot(1e3 * this_overlay_times, 0.5 + np.arange(len(this_data)),
                      'k', linewidth=2)
-        ax2 = plt.subplot2grid((3, 10), (2, 0), colspan=9, rowspan=1)
-        if colorbar:
-            ax3 = plt.subplot2grid((3, 10), (0, 9), colspan=1, rowspan=3)
         ax1.set_title(epochs.ch_names[idx])
         ax1.set_ylabel('Epochs')
         ax1.axis('auto')