Visualizing Evoked data

This tutorial shows the different visualization methods for :class:~mne.Evoked objects. :depth: 2

As usual we'll start by importing the modules we need:

Instead of creating the ~mne.Evoked object from an ~mne.Epochs object, we'll load an existing ~mne.Evoked object from disk. Remember, the :file:.fif format can store multiple ~mne.Evoked objects, so we'll end up with a list of ~mne.Evoked objects after loading. Recall also from the tut-section-load-evk section of `the introductory Evoked tutorial

that the sample~mne.Evoked` objects have not been baseline-corrected and have unapplied projectors, so we'll take care of that when loading:

To make our life easier, let's convert that list of :class:~mne.Evoked objects into a :class:dictionary <dict>. We'll use /-separated dictionary keys to encode the conditions (like is often done when epoching) because some of the plotting methods can take advantage of that style of coding.

Plotting signal traces

.. sidebar:: Butterfly plots

Plots of superimposed sensor timeseries are called "butterfly plots" because the positive- and negative-going traces can resemble butterfly wings.

The most basic plot of :class:~mne.Evoked objects is a butterfly plot of each channel type, generated by the :meth:evoked.plot() <mne.Evoked.plot> method. By default, channels marked as "bad" are suppressed, but you can control this by passing an empty :class:list to the exclude parameter (default is exclude='bads'):

Notice the completely flat EEG channel and the noisy gradiometer channel plotted in red color. Like many MNE-Python plotting functions, :meth:evoked.plot() <mne.Evoked.plot> has a picks parameter that can select channels to plot by name, index, or type. In the next plot we'll show only magnetometer channels, and also color-code the channel traces by their location by passing spatial_colors=True. Finally, we'll superimpose a trace of the :term:global field power <GFP> across channels:

Plotting scalp topographies

In an interactive session, the butterfly plots seen above can be click-dragged to select a time region, which will pop up a map of the average field distribution over the scalp for the selected time span. You can also generate scalp topographies at specific times or time spans using the :meth:~mne.Evoked.plot_topomap method:

Additional examples of plotting scalp topographies can be found in ex-evoked-topomap.

Arrow maps

Scalp topographies at a given time point can be augmented with arrows to show the estimated magnitude and direction of the magnetic field, using the function :func:mne.viz.plot_arrowmap:

Joint plots

Joint plots combine butterfly plots with scalp topographies, and provide an excellent first-look at evoked data; by default, topographies will be automatically placed based on peak finding. Here we plot the right-visual-field condition; if no picks are specified we get a separate figure for each channel type:

Like :meth:~mne.Evoked.plot_topomap you can specify the times at which you want the scalp topographies calculated, and you can customize the plot in various other ways as well. See :meth:mne.Evoked.plot_joint for details.

Comparing Evoked objects

To compare :class:~mne.Evoked objects from different experimental conditions, the function :func:mne.viz.plot_compare_evokeds can take a :class:list or :class:dict of :class:~mne.Evoked objects and plot them all on the same axes. Like most MNE-Python visualization functions, it has a picks parameter for selecting channels, but by default will generate one figure for each channel type, and combine information across channels of the same type by calculating the :term:global field power <GFP>. Information may be combined across channels in other ways too; support for combining via mean, median, or standard deviation are built-in, and custom callable functions may also be used, as shown here:

One nice feature of :func:~mne.viz.plot_compare_evokeds is that when passing evokeds in a dictionary, it allows specifying plot styles based on /-separated substrings of the dictionary keys (similar to epoch selection; see tut-section-subselect-epochs). Here, we specify colors for "aud" and "vis" conditions, and linestyles for "left" and "right" conditions, and the traces and legend are styled accordingly.

Image plots

Like :class:~mne.Epochs, :class:~mne.Evoked objects also have a :meth:~mne.Evoked.plot_image method, but unlike :meth:`epochs.plot_image()

<mne.Epochs.plot_image>, :meth:evoked.plot_image() <mne.Evoked.plot_image>shows one *channel* per row instead of one *epoch* per row. Again, a ``picks`` parameter is available, as well as several other customization options; see :meth:~mne.Evoked.plot_image` for details.

Topographical subplots

For sensor-level analyses it can be useful to plot the response at each sensor in a topographical layout. The :func:~mne.viz.plot_compare_evokeds function can do this if you pass axes='topo', but it can be quite slow if the number of sensors is too large, so here we'll plot only the EEG channels:

For larger numbers of sensors, the method :meth:`evoked.plot_topo()

<mne.Evoked.plot_topo>and the function :func:mne.viz.plot_evoked_topocan both be used. The :meth:~mne.Evoked.plot_topomethod will plot only a single condition, while the :func:~mne.viz.plot_evoked_topofunction can plot one or more conditions on the same axes, if passed a list of :class:~mne.Evokedobjects. The legend entries will be automatically drawn from the :class:~mne.Evoked` objects' comment attribute:

By default, :func:~mne.viz.plot_evoked_topo will plot all MEG sensors (if present), so to get EEG sensors you would need to modify the evoked objects first (e.g., using :func:mne.pick_types).

3D Field Maps

The scalp topographies above were all projected into 2-dimensional overhead views of the field, but it is also possible to plot field maps in 3D. To do this requires a :term:trans file to transform locations between the coordinate systems of the MEG device and the head surface (based on the MRI). You can compute 3D field maps without a trans file, but it will only work for calculating the field on the MEG helmet from the MEG sensors.

By default, MEG sensors will be used to estimate the field on the helmet surface, while EEG sensors will be used to estimate the field on the scalp. Once the maps are computed, you can plot them with :meth:`evoked.plot_field()

<mne.Evoked.plot_field>`:

You can also use MEG sensors to estimate the scalp field by passing meg_surf='head'. By selecting each sensor type in turn, you can compare the scalp field estimates from each.