mne.viz.plot_compare_evokeds

mne.viz.plot_compare_evokeds(evokeds, picks=None, gfp=None, colors=None, linestyles=None, styles=None, cmap=None, vlines='auto', ci=True, truncate_yaxis='auto', truncate_xaxis=True, ylim=None, invert_y=False, show_sensors=None, show_legend=None, legend=True, split_legend=None, axes=None, title=None, show=True, combine=None)[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.

gfpNone

Changed in version 0.19: The gfp parameter is deprecated and will be removed in version 0.20. Use combine='gfp' instead.

colorslist | dict | None

Colors to use when plotting the ERP/F lines and confidence bands. If cmap is not None, colors must be a list or dict of ints or floats indicating steps or percentiles (respectively) along the colormap. If cmap is None, list elements or dict values of colors must be ints or valid matplotlib colors; lists are cycled through sequentially, while dicts must have keys matching the keys or conditions of an evokeds dict (see Notes for details). If None, the current matplotlib color cycle is used. Defaults to None.

linestyleslist | dict | None

Styles to use when plotting the ERP/F lines. If a list or dict, elements must be valid matplotlib linestyles. Lists are cycled through sequentially; dictionaries must have keys matching the keys or conditions of an evokeds dict (see Notes for details). If None, all lines will be solid. Defaults to None.

stylesdict | None

Dictionary of styles to use when plotting ERP/F lines. Keys must match keys or conditions of evokeds, and values must be a dict of legal inputs to matplotlib.pyplot.plot(). Those values will be passed as parameters to the line plot call of the corresponding condition, overriding defaults (e.g., styles={"Aud/L": {"linewidth": 3}} will set the linewidth for “Aud/L” to 3). As with colors and linestyles, keys matching conditions in /-separated evokeds keys are supported (see Notes for details).

cmapNone | str | tuple | instance of matplotlib.colors.Colormap

Colormap from which to draw color values when plotting the ERP/F lines and confidence bands. If not None, ints or floats in the colors parameter are mapped to steps or percentiles (respectively) along the colormap. If cmap is a str, it will be passed to matplotlib.cm.get_cmap(); if cmap is a tuple, its first element will be used as a string to label the colorbar, and its second element will be passed to matplotlib.cm.get_cmap() (unless it is already an instance of Colormap).

Changed in version 0.19: Support for passing Colormap instances.

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 | bool | callable() | None

Confidence band around each ERP/F time series. If False or None no confidence band is drawn. If float, ci must be between 0 and 1, and will set the threshold for a bootstrap (single plot)/parametric (when axes=='topo') estimation of the confidence band; True is equivalent to setting a threshold of 0.95 (i.e., the 95% confidence band is drawn). If a callable, it must take a single array (n_observations × n_times) as input and return upper and lower confidence margins (2 × n_times). Defaults to True.

truncate_yaxisbool | ‘auto’

Whether to shorten the y-axis spine. If ‘auto’, the spine is truncated at the minimum and maximum ticks. If True, it is truncated at the multiple of 0.25 nearest to half the maximum absolute value of the data. If truncate_xaxis=False, only the far bound of the y-axis will be truncated. Defaults to ‘auto’.

truncate_xaxisbool

Whether to shorten the x-axis spine. If True, the spine is truncated at the minimum and maximum ticks. If truncate_yaxis=False, only the far bound of the x-axis will be truncated. Defaults to True.

ylimdict | None

Y-axis limits for plots (after scaling has been applied). dict keys should match channel types; valid keys are eeg, mag, grad, misc (example: ylim=dict(eeg=[-20, 20])). If None, the y-axis limits will be set automatically by matplotlib. Defaults to None.

invert_ybool

Whether to plot negative values upward (as is sometimes done for ERPs out of tradition). Defaults to False.

show_sensorsbool | int | str | None

Whether to display an inset showing sensor locations on a head outline. If int or str, indicates position of the inset (see mpl_toolkits.axes_grid1.inset_locator.inset_axes()). If None, treated as True if there is only one channel in picks. If True, location is upper or lower right corner, depending on data values. Defaults to None.

show_legendNone

Changed in version 0.19: The show_legend parameter has been renamed to legend, and will be removed in version 0.20.

legendbool | int | str

Whether to show a legend for the colors/linestyles of the conditions plotted. If int or str, indicates position of the legend (see mpl_toolkits.axes_grid1.inset_locator.inset_axes()). If True, equivalent to 'upper left'. Defaults to True.

split_legendbool | None

Whether to separate color and linestyle in the legend. If None, a separate linestyle legend will still be shown if cmap is specified. Defaults to None.

axesNone | Axes instance | list of Axes | ‘topo’

Axes object to plot into. If plotting multiple channel types (or multiple channels when combine=None), axes should be a list of appropriate length containing Axes objects. If 'topo', a new Figure is created with one axis for each channel, in a topographical layout. If None, a new Figure is created for each channel type. Defaults to None.

titlestr | None

Title printed above the plot. If None, a title will be automatically generated based on channel name(s) or type(s) and the value of the combine parameter. Defaults to None.

showbool

Whether to show the figure. Defaults to True.

combineNone | str | callable()

How to combine information across channels. If a str, must be one of ‘mean’, ‘median’, ‘std’ (standard deviation) or ‘gfp’ (global field power). If callable, the callable must accept one positional input (data of shape (n_evokeds, n_channels, n_times)) and return an array of shape (n_epochs, n_times). For example:

combine = lambda data: np.median(data, axis=1)

If combine is None, channels are combined by computing GFP, unless picks is a single channel (not channel type) or axes='topo', in which cases no combining is performed. Defaults to None.

Returns
figlist of Figure instances

A list of the figure(s) generated.

Notes

If the parameters styles, colors, or linestyles are passed as dicts, then evokeds must also be a dict, and the keys of the plot-style parameters must either match the keys of evokeds, or match a /-separated partial key (“condition”) of evokeds. For example, if evokeds has keys “Aud/L”, “Aud/R”, “Vis/L”, and “Vis/R”, then linestyles=dict(L='--', R='-') will plot both Aud/L and Vis/L conditions with dashed lines and both Aud/R and Vis/R conditions with solid lines. Similarly, colors=dict(Aud='r', Vis='b') will plot Aud/L and Aud/R conditions red and Vis/L and Vis/R conditions blue.

Color specification depends on whether a colormap has been provided in the cmap parameter. The following table summarizes how the colors parameter is interpreted:

cmap

colors

result

None

None

matplotlib default color cycle; unique color for each condition

list or dict of integers

matplotlib default color cycle; lowest integer mapped to first cycle color; conditions with same integer get same color; unspecified conditions are “gray”

list or dict of floats

ValueError

list or dict of hexadecimal color strings

the specified hex colors; unspecified conditions are “gray”

string or instance of matplotlib Colormap

None

equally spaced colors on the colormap; unique color for each condition

list or dict of integers

equally spaced colors on the colormap; lowest integer mapped to first cycle color; conditions with same integer get same color

list or dict of floats

floats mapped to corresponding colormap values

list or dict of hexadecimal color strings

TypeError