"""Functions to plot epochs data """ from __future__ import print_function # Authors: Alexandre Gramfort # Denis Engemann # Martin Luessi # Eric Larson # # License: Simplified BSD import warnings from collections import deque from functools import partial import numpy as np from scipy import ndimage from ..utils import create_chunks from ..io.pick import pick_types, channel_type from ..fixes import Counter from .utils import _mutable_defaults, tight_layout, _prepare_trellis from .utils import figure_nobar def plot_image_epochs(epochs, picks=None, sigma=0.3, vmin=None, vmax=None, colorbar=True, order=None, show=True, units=None, scalings=None, cmap='RdBu_r'): """Plot Event Related Potential / Fields image Parameters ---------- epochs : instance of Epochs The epochs picks : int | array-like of int | None The indices of the channels to consider. If None, all good data channels are plotted. sigma : float The standard deviation of the Gaussian smoothing to apply along the epoch axis to apply in the image. 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 or not the figure at the end 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)` cmap : matplotlib colormap Colormap. Returns ------- figs : the list of matplotlib figures One figure per channel displayed """ units, scalings = _mutable_defaults(('units', units), ('scalings', scalings)) import matplotlib.pyplot as plt if picks is None: picks = pick_types(epochs.info, meg=True, eeg=True, ref_meg=False, exclude='bads') if list(units.keys()) != list(scalings.keys()): raise ValueError('Scalings and units must have the same keys.') picks = np.atleast_1d(picks) evoked = epochs.average(picks) data = epochs.get_data()[:, picks, :] if vmin is None: vmin = data.min() if vmax is None: vmax = data.max() figs = list() for i, (this_data, idx) in enumerate(zip(np.swapaxes(data, 0, 1), picks)): this_fig = plt.figure() figs.append(this_fig) ch_type = channel_type(epochs.info, idx) if not ch_type in scalings: # We know it's not in either scalings or units since keys match raise KeyError('%s type not in scalings and units' % ch_type) this_data *= scalings[ch_type] this_order = order if callable(order): this_order = order(epochs.times, this_data) if this_order is not None: this_data = this_data[this_order] this_data = ndimage.gaussian_filter1d(this_data, sigma=sigma, axis=0) ax1 = plt.subplot2grid((3, 10), (0, 0), colspan=9, rowspan=2) im = plt.imshow(this_data, extent=[1e3 * epochs.times[0], 1e3 * epochs.times[-1], 0, len(data)], aspect='auto', origin='lower', vmin=vmin, vmax=vmax, cmap=cmap) 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') ax1.axis('tight') ax1.axvline(0, color='m', linewidth=3, linestyle='--') ax2.plot(1e3 * evoked.times, scalings[ch_type] * evoked.data[i]) ax2.set_xlabel('Time (ms)') ax2.set_ylabel(units[ch_type]) ax2.set_ylim([vmin, vmax]) ax2.axvline(0, color='m', linewidth=3, linestyle='--') if colorbar: plt.colorbar(im, cax=ax3) tight_layout(fig=this_fig) if show: plt.show() return figs def _drop_log_stats(drop_log, ignore=['IGNORED']): """ Parameters ---------- drop_log : list of lists Epoch drop log from Epochs.drop_log. ignore : list The drop reasons to ignore. Returns ------- perc : float Total percentage of epochs dropped. """ # XXX: This function should be moved to epochs.py after # removal of perc return parameter in plot_drop_log() if not isinstance(drop_log, list) or not isinstance(drop_log[0], list): raise ValueError('drop_log must be a list of lists') perc = 100 * np.mean([len(d) > 0 for d in drop_log if not any([r in ignore for r in d])]) return perc def plot_drop_log(drop_log, threshold=0, n_max_plot=20, subject='Unknown', color=(0.9, 0.9, 0.9), width=0.8, ignore=['IGNORED'], show=True, return_fig=False): """Show the channel stats based on a drop_log from Epochs Parameters ---------- drop_log : list of lists Epoch drop log from Epochs.drop_log. threshold : float The percentage threshold to use to decide whether or not to plot. Default is zero (always plot). n_max_plot : int Maximum number of channels to show stats for. subject : str The subject name to use in the title of the plot. color : tuple | str Color to use for the bars. width : float Width of the bars. ignore : list The drop reasons to ignore. show : bool Show figure if True. return_fig : bool Return only figure handle if True. This argument will default to True in v0.9 and then be removed. Returns ------- perc : float Total percentage of epochs dropped. fig : Instance of matplotlib.figure.Figure The figure. """ import matplotlib.pyplot as plt perc = _drop_log_stats(drop_log, ignore) scores = Counter([ch for d in drop_log for ch in d if ch not in ignore]) ch_names = np.array(list(scores.keys())) if perc < threshold or len(ch_names) == 0: return perc counts = 100 * np.array(list(scores.values()), dtype=float) / len(drop_log) n_plot = min(n_max_plot, len(ch_names)) order = np.flipud(np.argsort(counts)) fig = plt.figure() plt.title('%s: %0.1f%%' % (subject, perc)) x = np.arange(n_plot) plt.bar(x, counts[order[:n_plot]], color=color, width=width) plt.xticks(x + width / 2.0, ch_names[order[:n_plot]], rotation=45, horizontalalignment='right') plt.tick_params(axis='x', which='major', labelsize=10) plt.ylabel('% of epochs rejected') plt.xlim((-width / 2.0, (n_plot - 1) + width * 3 / 2)) plt.grid(True, axis='y') if show: plt.show() if return_fig: return fig else: msg = ("'return_fig=False' will be deprecated in v0.9. " "Use 'Epochs.drop_log_stats' to get percentages instead.") warnings.warn(msg, DeprecationWarning) return perc, fig def _draw_epochs_axes(epoch_idx, good_ch_idx, bad_ch_idx, data, times, axes, title_str, axes_handler): """Aux functioin""" this = axes_handler[0] for ii, data_, ax in zip(epoch_idx, data, axes): [l.set_data(times, d) for l, d in zip(ax.lines, data_[good_ch_idx])] if bad_ch_idx is not None: bad_lines = [ax.lines[k] for k in bad_ch_idx] [l.set_data(times, d) for l, d in zip(bad_lines, data_[bad_ch_idx])] if title_str is not None: ax.set_title(title_str % ii, fontsize=12) ax.set_ylim(data.min(), data.max()) ax.set_yticks([]) ax.set_xticks([]) if vars(ax)[this]['reject'] is True: # memorizing reject [l.set_color((0.8, 0.8, 0.8)) for l in ax.lines] ax.get_figure().canvas.draw() else: # forgetting previous reject for k in axes_handler: if k == this: continue if vars(ax).get(k, {}).get('reject', None) is True: [l.set_color('k') for l in ax.lines[:len(good_ch_idx)]] if bad_ch_idx is not None: [l.set_color('r') for l in ax.lines[-len(bad_ch_idx):]] ax.get_figure().canvas.draw() break def _epochs_navigation_onclick(event, params): """Aux function""" import matplotlib.pyplot as plt p = params here = None if event.inaxes == p['back'].ax: here = 1 elif event.inaxes == p['next'].ax: here = -1 elif event.inaxes == p['reject-quit'].ax: if p['reject_idx']: p['epochs'].drop_epochs(p['reject_idx']) plt.close(p['fig']) plt.close(event.inaxes.get_figure()) if here is not None: p['idx_handler'].rotate(here) p['axes_handler'].rotate(here) this_idx = p['idx_handler'][0] _draw_epochs_axes(this_idx, p['good_ch_idx'], p['bad_ch_idx'], p['data'][this_idx], p['times'], p['axes'], p['title_str'], p['axes_handler']) # XXX don't ask me why p['axes'][0].get_figure().canvas.draw() def _epochs_axes_onclick(event, params): """Aux function""" reject_color = (0.8, 0.8, 0.8) ax = event.inaxes if event.inaxes is None: return p = params here = vars(ax)[p['axes_handler'][0]] if here.get('reject', None) is False: idx = here['idx'] if idx not in p['reject_idx']: p['reject_idx'].append(idx) [l.set_color(reject_color) for l in ax.lines] here['reject'] = True elif here.get('reject', None) is True: idx = here['idx'] if idx in p['reject_idx']: p['reject_idx'].pop(p['reject_idx'].index(idx)) good_lines = [ax.lines[k] for k in p['good_ch_idx']] [l.set_color('k') for l in good_lines] if p['bad_ch_idx'] is not None: bad_lines = ax.lines[-len(p['bad_ch_idx']):] [l.set_color('r') for l in bad_lines] here['reject'] = False ax.get_figure().canvas.draw() def plot_epochs(epochs, epoch_idx=None, picks=None, scalings=None, title_str='#%003i', show=True, block=False): """ Visualize single trials using Trellis plot. Parameters ---------- epochs : instance of Epochs The epochs object epoch_idx : array-like | int | None The epochs to visualize. If None, the first 20 epochs are shown. Defaults to None. picks : array-like of int | None Channels to be included. If None only good data channels are used. Defaults to None scalings : dict | None Scale factors for the traces. If None, defaults to: `dict(mag=1e-12, grad=4e-11, eeg=20e-6, eog=150e-6, ecg=5e-4, emg=1e-3, ref_meg=1e-12, misc=1e-3, stim=1, resp=1, chpi=1e-4)` title_str : None | str The string formatting to use for axes titles. If None, no titles will be shown. Defaults expand to ``#001, #002, ...`` show : bool Whether to show the figure or not. block : bool Whether to halt program execution until the figure is closed. Useful for rejecting bad trials on the fly by clicking on a sub plot. Returns ------- fig : Instance of matplotlib.figure.Figure The figure. """ import matplotlib.pyplot as plt import matplotlib as mpl scalings = _mutable_defaults(('scalings_plot_raw', None))[0] if np.isscalar(epoch_idx): epoch_idx = [epoch_idx] if epoch_idx is None: n_events = len(epochs.events) epoch_idx = list(range(n_events)) else: n_events = len(epoch_idx) epoch_idx = epoch_idx[:n_events] idx_handler = deque(create_chunks(epoch_idx, 20)) if picks is None: if any('ICA' in k for k in epochs.ch_names): picks = pick_types(epochs.info, misc=True, ref_meg=False, exclude=[]) else: picks = pick_types(epochs.info, meg=True, eeg=True, ref_meg=False, exclude=[]) if len(picks) < 1: raise RuntimeError('No appropriate channels found. Please' ' check your picks') times = epochs.times * 1e3 n_channels = epochs.info['nchan'] types = [channel_type(epochs.info, idx) for idx in picks] # preallocation needed for min / max scaling data = np.zeros((len(epochs.events), n_channels, len(times))) for ii, epoch in enumerate(epochs.get_data()): for jj, (this_type, this_channel) in enumerate(zip(types, epoch)): data[ii, jj] = this_channel / scalings[this_type] n_events = len(epochs.events) epoch_idx = epoch_idx[:n_events] idx_handler = deque(create_chunks(epoch_idx, 20)) # handle bads bad_ch_idx = None ch_names = epochs.ch_names bads = epochs.info['bads'] if any([ch_names[k] in bads for k in picks]): ch_picked = [k for k in ch_names if ch_names.index(k) in picks] bad_ch_idx = [ch_picked.index(k) for k in bads if k in ch_names] good_ch_idx = [p for p in picks if p not in bad_ch_idx] else: good_ch_idx = np.arange(n_channels) fig, axes = _prepare_trellis(len(data[idx_handler[0]]), max_col=5) axes_handler = deque(list(range(len(idx_handler)))) for ii, data_, ax in zip(idx_handler[0], data[idx_handler[0]], axes): ax.plot(times, data_[good_ch_idx].T, color='k') if bad_ch_idx is not None: ax.plot(times, data_[bad_ch_idx].T, color='r') if title_str is not None: ax.set_title(title_str % ii, fontsize=12) ax.set_ylim(data.min(), data.max()) ax.set_yticks([]) ax.set_xticks([]) vars(ax)[axes_handler[0]] = {'idx': ii, 'reject': False} # initialize memory for this_view, this_inds in zip(axes_handler, idx_handler): for ii, ax in zip(this_inds, axes): vars(ax)[this_view] = {'idx': ii, 'reject': False} tight_layout(fig=fig) navigation = figure_nobar(figsize=(3, 1.5)) from matplotlib import gridspec gs = gridspec.GridSpec(2, 2) ax1 = plt.subplot(gs[0, 0]) ax2 = plt.subplot(gs[0, 1]) ax3 = plt.subplot(gs[1, :]) params = { 'fig': fig, 'idx_handler': idx_handler, 'epochs': epochs, 'picks': picks, 'times': times, 'scalings': scalings, 'good_ch_idx': good_ch_idx, 'bad_ch_idx': bad_ch_idx, 'axes': axes, 'back': mpl.widgets.Button(ax1, 'back'), 'next': mpl.widgets.Button(ax2, 'next'), 'reject-quit': mpl.widgets.Button(ax3, 'reject-quit'), 'title_str': title_str, 'reject_idx': [], 'axes_handler': axes_handler, 'data': data } fig.canvas.mpl_connect('button_press_event', partial(_epochs_axes_onclick, params=params)) navigation.canvas.mpl_connect('button_press_event', partial(_epochs_navigation_onclick, params=params)) if show is True: plt.show(block=block) return fig