mne.viz.plot_compare_evokeds

mne.viz.plot_compare_evokeds(evokeds, picks=None, gfp=False, colors=None, linestyles=['-'], styles=None, cmap=None, vlines='auto', ci=0.95, truncate_yaxis='max_ticks', truncate_xaxis=True, ylim=None, invert_y=False, show_sensors=None, show_legend=True, split_legend=False, axes=None, title=None, show=True)[source]

Plot evoked time courses for one or more conditions and/or channels.

Parameters
evokedsinstance of mne.Evoked | list | dict

If a single Evoked instance, it is plotted as a time series. If a dict whose values are Evoked objects, the contents are plotted as single time series each and the keys are used as condition labels. If a list of Evokeds, the contents are plotted with indices as labels. If a [dict/list] of lists, the unweighted mean is plotted as a time series and the parametric confidence interval is plotted as a shaded area. All instances must have the same shape - channel numbers, time points etc. If dict, keys must be of type str.

picksstr | list | slice | None

Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values “all” to pick all channels, or “data” to pick data channels. None (default) will pick all data channels.

  • If picks is None or a (collection of) data channel types, the global field power will be plotted for all data channels. Otherwise, picks will be averaged.

  • If multiple channel types are selected, one figure will be returned for each channel type.

  • If the selected channels are gradiometers, the signal from corresponding (gradiometer) pairs will be combined.

gfpbool

If True, the channel type wise GFP is plotted. If None and picks is None or a (list of) channel type(s), this is set to True.

colorslist | dict | None

If a list, will be sequentially used for line colors. If a dict, can map evoked keys or ‘/’-separated (HED) tags to conditions. For example, if evokeds is a dict with the keys “Aud/L”, “Aud/R”, “Vis/L”, “Vis/R”, colors can be dict(Aud=’r’, Vis=’b’) to map both Aud/L and Aud/R to the color red and both Visual conditions to blue. If None (default), a sequence of desaturated colors is used. If cmap is None, colors will indicate how each condition is colored with reference to its position on the colormap - see cmap below. In that case, the values of colors must be either integers, in which case they will be mapped to colors in rank order; or floats between 0 and 1, in which case they will be mapped to percentiles of the colormap.

linestyleslist | dict

If a list, will be sequentially and repeatedly used for evoked plot linestyles. If a dict, can map the evokeds keys or ‘/’-separated (HED) tags to conditions. For example, if evokeds is a dict with the keys “Aud/L”, “Aud/R”, “Vis/L”, “Vis/R”, linestyles can be dict(L=’–’, R=’-‘) to map both Aud/L and Vis/L to dashed lines and both Right-side conditions to straight lines.

stylesdict | None

If a dict, keys must map to evoked keys or conditions, and values must be a dict of legal inputs to matplotlib.pyplot.plot. These parameters will be passed to the line plot call of the corresponding condition, overriding defaults. E.g., if evokeds is a dict with the keys “Aud/L”, “Aud/R”, “Vis/L”, “Vis/R”, styles can be {“Aud/L”: {“linewidth”: 1}} to set the linewidth for “Aud/L” to 1. Note that HED (‘/’-separated) tags are not supported.

cmapNone | str | tuple

If not None, plot evoked activity with colors from a color gradient (indicated by a str referencing a matplotlib colormap - e.g., “viridis” or “Reds”). If evokeds is a list and colors is None, the color will depend on the list position. If colors is a list, it must contain integers where the list positions correspond to evokeds, and the value corresponds to the position on the colorbar. If evokeds is a dict, colors should be a dict mapping from (potentially HED-style) condition tags to numbers corresponding to positions on the colorbar - rank order for integers, or floats for percentiles. E.g.,

evokeds={"cond1/A": ev1, "cond2/A": ev2, "cond3/A": ev3, "B": ev4},
cmap='viridis', colors=dict(cond1=1 cond2=2, cond3=3),
linestyles={"A": "-", "B": ":"}

If cmap is a tuple of length 2, the first item must be a string which will become the colorbar label, and the second one must indicate a colormap, e.g.

cmap=('conds', 'viridis'), colors=dict(cond1=1 cond2=2, cond3=3),
vlines“auto” | list of float

A list in seconds at which to plot dashed vertical lines. If “auto” and the supplied data includes 0, it is set to [0.] and a vertical bar is plotted at time 0. If an empty list is passed, no vertical lines are plotted.

cifloat | callable() | None | bool

If not None and evokeds is a [list/dict] of lists, a shaded confidence interval is drawn around the individual time series. If float, a percentile bootstrap method is used to estimate the confidence interval and this value determines the CI width. E.g., if this value is .95 (the default), the 95% confidence interval is drawn. If a callable, it must take as its single argument an array (observations x times) and return the upper and lower confidence bands. If None or False, no confidence band is plotted. If True, a 95% bootstrapped confidence interval is drawn.

truncate_yaxisbool | str

If not False, the left y axis spine is truncated to reduce visual clutter. If ‘max_ticks’, the spine is truncated at the minimum and maximum ticks. Else, it is truncated to half the max absolute value, rounded to .25. Defaults to “max_ticks”.

truncate_xaxisbool

If True, the x axis is truncated to span from the first to the last. xtick. Defaults to True.

ylimdict | None

ylim for plots (after scaling has been applied). e.g. ylim = dict(eeg=[-20, 20]) Valid keys are eeg, mag, grad, misc. If None, the ylim parameter for each channel equals the pyplot default. Defaults to None.

invert_ybool

If True, negative values are plotted up (as is sometimes done for ERPs out of tradition). Defaults to False.

show_sensors: bool | int | str | None

If not False, channel locations are plotted on a small head circle. If int or str, the position of the axes (forwarded to mpl_toolkits.axes_grid1.inset_locator.inset_axes). If None, defaults to True if gfp is False, else to False.

show_legendbool | str | int

If not False, show a legend. If int or str, it is the position of the legend axes (forwarded to mpl_toolkits.axes_grid1.inset_locator.inset_axes).

split_legendbool

If True, the legend shows color and linestyle separately; colors must not be None. Defaults to True if cmap is not None, else defaults to False.

axesNone | matplotlib.axes.Axes instance | list of axes | “topo”

What axes to plot to. If None, a new axes is created. If “topo”, separately for each channel type, a new figure is created with one axis for each channel in a topographical layout. In this case, gfp is ignored. When plotting multiple channel types, can also be a list of axes, one per channel type.

titleNone | str

If str, will be plotted as figure title. If None, the channel names will be shown.

showbool

If True, show the figure.

Returns
figFigure | list of Figure

The figure(s) in which the plot is drawn. When plotting multiple channel types, a list of figures, one for each channel type is returned.

Notes

When multiple channels are passed, this function combines them all, to get one time course for each condition. If gfp is True it combines channels using global field power (GFP) computation, else it is taking a plain mean.

This function is useful for comparing multiple ER[P/F]s - e.g., for multiple conditions - at a specific location.

It can plot:

  • a simple mne.Evoked object,

  • a list or dict of mne.Evoked objects (e.g., for multiple conditions),

  • a list or dict of lists of mne.Evoked (e.g., for multiple subjects in multiple conditions).

In the last case, it can show a confidence interval (across e.g. subjects) using parametric or bootstrap estimation.

When picks includes more than one planar gradiometer, the planar gradiometers are combined with RMSE. For example data from a VectorView system with 204 gradiometers will be transformed to 102 channels.