mne.viz.plot_compare_evokeds#

mne.viz.plot_compare_evokeds(evokeds, picks=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, legend=True, split_legend=None, axes=None, title=None, show=True, combine=None, sphere=None, time_unit='s')[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 list of Evokeds, the contents are plotted with their .comment attributes used as condition labels. If no comment is set, the index of the respective Evoked the list will be used instead, starting with 1 for the first Evoked. If a dict whose values are Evoked objects, the contents are plotted as single time series each and the keys are used 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 | array_like | 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. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.

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.

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.colormaps; 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.colormaps (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.

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.

The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. If 'auto' the sphere is fit to digitization points. If 'eeglab' the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz'). None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

New in version 0.20.

Changed in version 1.1: Added 'eeglab' option.

time_unitstr

The units for the time axis, can be “s” (default) or “ms”.

New in version 1.1.

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`