Grand Averages and Visualization#
In this lesson and the next, we’ll work with data from a group of participants, with the aim of testing an experimental hypothesis. The present data do not come from the same experiment as generated the individual participant ERP data we’ve worked with so far. However, they come from another experiment in which an N400 was also predicted. In this experiment, people read sentences that ended in either a semantically congruent word (e.g., I take my coffee with milk and sugar), or an incongruent word (e.g., I take my coffee with milk and glass.). But, similar to the previous experiment, we still predicted an N400 effect, with more negative ERPs for incongruent words than congruent words. Our hypothesis was that there would be a significantly greater negativity, between 400–600 ms, largest over midline central-posterior channels (Cz, CPz, Pz), for incongruent words than congruent words.
The data set comprises preprocessed data files in MNE’s .fif format, one for each participant. The data were preprocessed using the same steps as in the previous lesson, and the data files are named according to the experiment and participant number. For example, the data file for participant 1 is named sentence_n400_p01-ave.fif. Each data set contains data from approximately 80 trials (40 each of Violation and Control) and 64 channels.
The first thing we want to do, when working with ERP data at the group level, is to load in each individual’s preprocessed data, and then calculate the grand average (an average across a group of participants). We will then plot the grand average ERPs, as waveforms and topo plots, to see how the conditions vary at the group level.
Load packages#
import mne
mne.set_log_level('error') # reduce extraneous MNE output
import matplotlib.pyplot as plt
import numpy as np
import glob
---------------------------------------------------------------------------
ImportError Traceback (most recent call last)
Cell In[1], line 1
----> 1 import mne
2 mne.set_log_level('error') # reduce extraneous MNE output
3 import matplotlib.pyplot as plt
File ~/miniforge3/envs/neural_data_science/lib/python3.12/site-packages/mne/__init__.py:22
19 __version__ = '0.16.2'
21 # have to import verbose first since it's needed by many things
---> 22 from .utils import (set_log_level, set_log_file, verbose, set_config,
23 get_config, get_config_path, set_cache_dir,
24 set_memmap_min_size, grand_average, sys_info, open_docs)
25 from .io.pick import (pick_types, pick_channels,
26 pick_channels_regexp, pick_channels_forward,
27 pick_types_forward, pick_channels_cov,
28 pick_channels_evoked, pick_info)
29 from .io.base import concatenate_raws
File ~/miniforge3/envs/neural_data_science/lib/python3.12/site-packages/lazy_loader/__init__.py:82, in attach.<locals>.__getattr__(name)
80 elif name in attr_to_modules:
81 submod_path = f"{package_name}.{attr_to_modules[name]}"
---> 82 submod = importlib.import_module(submod_path)
83 attr = getattr(submod, name)
85 # If the attribute lives in a file (module) with the same
86 # name as the attribute, ensure that the attribute and *not*
87 # the module is accessible on the package.
File ~/miniforge3/envs/neural_data_science/lib/python3.12/importlib/__init__.py:90, in import_module(name, package)
88 break
89 level += 1
---> 90 return _bootstrap._gcd_import(name[level:], package, level)
File ~/miniforge3/envs/neural_data_science/lib/python3.12/site-packages/mne/utils/_logging.py:20
16 from typing import Any, Callable, TypeVar
18 from decorator import FunctionMaker
---> 20 from .docs import fill_doc
22 logger = logging.getLogger("mne") # one selection here used across mne-python
23 logger.propagate = False # don't propagate (in case of multiple imports)
File ~/miniforge3/envs/neural_data_science/lib/python3.12/site-packages/mne/utils/docs.py:17
13 from copy import deepcopy
15 from decorator import FunctionMaker
---> 17 from ..defaults import HEAD_SIZE_DEFAULT
18 from ._bunch import BunchConst
20 # # # WARNING # # #
21 # This list must also be updated in doc/_templates/autosummary/class.rst if it
22 # is changed here!
ImportError: cannot import name 'HEAD_SIZE_DEFAULT' from 'mne.defaults' (/Users/aaron/miniforge3/envs/neural_data_science/lib/python3.12/site-packages/mne/defaults.py)
Define parameters#
We define a list of experimental conditions; that’s about the only parameter we need to define here.
conditions = ['Control', 'Violation']
Find data files#
We list all the -ave.fif files (Evoked data sets) associated with this experiment:
data_dir = 'data/group_data/'
data_files = glob.glob(data_dir + 'sentence_n400_p*-ave.fif' )
data_files
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[3], line 2
1 data_dir = 'data/group_data/'
----> 2 data_files = glob.glob(data_dir + 'sentence_n400_p*-ave.fif' )
3 data_files
NameError: name 'glob' is not defined
Load data files#
In the previous lesson on averaging trials for an individual participant, we ended by saving the list of MNE Evoked objects (representing the averages across trials for each condition) in a single file for that participant.
Here, we will load in the files from a group of participants. To work with them easily and efficiently in MNE, we will store them as a dictionary, where each key is a condition label, and each value is a list of Evoked objects (the data from that condition, with each participant’s Evoked as a list item).
Here when we read_evokeds() you will likewise get a list of Evoked objects. Lists are a bit tricky since they don’t contain labels. In the previous lesson we addressed this by manually changing the .comment field of each Evoked object to clearly label it. As well, in the case of the present data (as is good practice in any data science pipeline), we used the same code to generate all of the Evoked files, so the two experimental conditions occur in the same order in each -ave.fif file. Since each participant’s data was saved in the same order, index 0 in the list will always be the same condition for all participants. For this reason, we can use enumerate() to loop over conditions and build our dictionary of Evoked objects here.
Note that we use list comprehension to build the list of Evoked objects for each condition, and we use the index from enumerate() (idx) to specify which condition (list item) we read from each participant’s data file:
evokeds = {}
for idx, c in enumerate(conditions):
evokeds[c] = [mne.read_evokeds(d)[idx].set_montage('easycap-M1') for d in data_files]
evokeds
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[4], line 4
1 evokeds = {}
3 for idx, c in enumerate(conditions):
----> 4 evokeds[c] = [mne.read_evokeds(d)[idx].set_montage('easycap-M1') for d in data_files]
6 evokeds
NameError: name 'data_files' is not defined
Compare Evoked waveforms#
mne.viz.plot_compare_evokeds() will recognize a dictionary of Evoked objects and use the keys as condition labels. Furthermore, when it sees that each value in the dictionary is a list of Evoked objects, it will combine them and plot not only the mean across the list (i.e., across participants, for each condition), but also the 95% confidence intervals (CIs), representing the variability across participants. As we learned in the [EDA] chapter, CIs are a useful way of visually assessing whether different conditions are likely to be statistically significantly different. In this case, the plot shows evidence of an N400 effect. The difference between conditions is largest between ~350–650 ms, and the CIs are most distinct (overlapping little or not at all) between 500–650 ms.
# Define plot parameters
roi = ['C3', 'Cz', 'C4',
'P3', 'Pz', 'P4']
# set custom line colors and styles
color_dict = {'Control':'blue', 'Violation':'red'}
linestyle_dict = {'Control':'-', 'Violation':'--'}
mne.viz.plot_compare_evokeds(evokeds,
combine='mean',
legend='lower right',
picks=roi, show_sensors='upper right',
colors=color_dict,
linestyles=linestyle_dict,
title='Violation vs. Control Waveforms'
)
plt.show()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[5], line 9
6 color_dict = {'Control':'blue', 'Violation':'red'}
7 linestyle_dict = {'Control':'-', 'Violation':'--'}
----> 9 mne.viz.plot_compare_evokeds(evokeds,
10 combine='mean',
11 legend='lower right',
12 picks=roi, show_sensors='upper right',
13 colors=color_dict,
14 linestyles=linestyle_dict,
15 title='Violation vs. Control Waveforms'
16 )
17 plt.show()
NameError: name 'mne' is not defined
Differences#
As we did in the single-participant analysis, we can also create difference waves to more easily visualize the difference between conditions, and compare it to zero (i.e., no difference between conditions).
In order to get CIs that reflect the variance across participants, we need to compute the Violation-Control difference separately for each participant. As we did for a single participant’s data, we use mne.combine_evoked() for this, with a weight of 1 for Violation and -1 for Control. The only difference here is we put this function in a list comprehension to loop over participants.
diff_waves = [mne.combine_evoked([evokeds['Violation'][subj],
evokeds['Control'][subj]
],
weights=[1, -1]
)
for subj in range(len(data_files))
]
diff_waves
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[6], line 6
1 diff_waves = [mne.combine_evoked([evokeds['Violation'][subj],
2 evokeds['Control'][subj]
3 ],
4 weights=[1, -1]
5 )
----> 6 for subj in range(len(data_files))
7 ]
8 diff_waves
NameError: name 'data_files' is not defined
Plot difference waveform#
In making the difference waveform above, we simply created a list of Evoked objects. We didn’t create a dictionary since there is only one contrast (Violation-Control), so no need to have informative dictionary keys for a set of different items (contrasts). This is fine, however MNE’s plot_compare_evokeds() has some complicated behavior when it comes to its inputs, and whether it draws CIs or not. Specifically, the API reads:
If a list of Evokeds, the contents are plotted with their .comment attributes used as condition labels… 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.
In other words, when the function gets a list of Evoked objects as input, it will draw each object as a separate waveform, but if it gets a dictionary in which each entry is a list of Evoked objects, if will average them together and draw CIs. Since we desire the latter behavior here, in the command below we create a dictionary “on the fly” inside the plotting command, with a key corresponding to the label we want, and the value being the list of difference waves.
contrast = 'Violation-Control'
mne.viz.plot_compare_evokeds({contrast:diff_waves}, combine='mean',
legend=None,
picks=roi, show_sensors='upper right',
title=contrast
)
plt.show()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[7], line 2
1 contrast = 'Violation-Control'
----> 2 mne.viz.plot_compare_evokeds({contrast:diff_waves}, combine='mean',
3 legend=None,
4 picks=roi, show_sensors='upper right',
5 title=contrast
6 )
7 plt.show()
NameError: name 'mne' is not defined
The nice thing about 95% CIs is that they provide an easy visual aid for interpreting the results. If the CI overlaps zero, then the difference between conditions is not statistically significant. If the CI does not overlap zero, then the difference can be considered statistically significant. In this case, the CI largely does not overlap zero between ~400–600 ms, so we can conclude that the difference between conditions is statistically significant in that time window.
Scalp topographic map#
As with plot_compare_evoked(), it’s important to understand what type of data the plot_evoked_topomap() function needs in order to get it to work right. Whereas plot_compare_evoked() will average over a list of Evoked objects, plot_evoked_topomap() will only accept a single Evoked object as input. Therefore, in the command below we apply the mne.grand_average() function to the list of Evoked objects (Grand averaging is a term used in EEG research to refer to an average across participants; this terminology developed to distinguish such an average from an average across trials, for a single participant).
Here we plot the topographic map for the average amplitude over a 200 ms period, centered on 400 ms (i.e., 300–500 ms).
mne.viz.plot_evoked_topomap(mne.grand_average(diff_waves),
times=.500, average=0.200,
size=3
)
plt.show()
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[8], line 1
----> 1 mne.viz.plot_evoked_topomap(mne.grand_average(diff_waves),
2 times=.500, average=0.200,
3 size=3
4 )
5 plt.show()
NameError: name 'mne' is not defined
We can add a few enhancements to the plot to make it more interpretable:
The
show_nameskwarg tells the function to plot the names of each channel. We also usesensors=Falseotherwise the dots for each channel would overlap the names.The
contours=Falsekwarg turns off the dashed contour lines you can see above. This is a matter of personal preference, however I feel that these are like non-continuous colour scales, in that they provide visual indicators of discontinuous “steps” in the scalp electrical potential values, when in fact these vary smoothly and continuously.We increase the
sizeto make the channel labels a bit easier to read (unfortunately the function doesn’t provide a kwarg to adjust the font size of these).
mne.viz.plot_evoked_topomap(mne.grand_average(diff_waves),
times=.500, average=0.200,
show_names=True, sensors=False,
contours=False,
size=4
);
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
Cell In[9], line 1
----> 1 mne.viz.plot_evoked_topomap(mne.grand_average(diff_waves),
2 times=.500, average=0.200,
3 show_names=True, sensors=False,
4 contours=False,
5 size=4
6 );
NameError: name 'mne' is not defined
Summary#
In this lesson we learned how to load in a group of Evoked objects, and how to use MNE’s plot_compare_evokeds() function to plot the average waveforms for each condition, and the 95% confidence intervals (CIs) for each. We also learned how to create difference waves, and plot the average difference wave with CIs. Finally, we learned how to plot a scalp topographic map of the average amplitude over a time window of interest. Of course, none of this tells us whether the Violation–Control difference is statistically significant. We will learn how to do that in the next lesson.