The Epochs data structure: epoched dataΒΆ

from __future__ import print_function

import mne
import os.path as op
import numpy as np
from matplotlib import pyplot as plt

Epochs objects are a way of representing continuous data as a collection of time-locked trials, stored in an array of shape(n_events, n_channels, n_times). They are useful for many statistical methods in neuroscience, and make it easy to quickly overview what occurs during a trial.

Epochs objects can be created in three ways:
  1. From a Raw object, along with event times
  2. From an Epochs object that has been saved as a .fif file
  3. From scratch using EpochsArray
# Load a dataset that contains events
raw = mne.io.RawFIF(
    op.join(mne.datasets.sample.data_path(), 'MEG', 'sample',
            'sample_audvis_raw.fif'))

# If your raw object has a stim channel, you can construct an event array
# easily
events = mne.find_events(raw, stim_channel='STI 014')

# Show the number of events (number of rows)
print('Number of events:', len(events))

# Show all unique event codes (3rd column)
print('Unique event codes:', np.unique(events[:, 2]))

# Specify event codes of interest with descriptive labels
event_id = dict(left=1, right=2)

Out:

Number of events: 320
Unique event codes: [ 1  2  3  4  5 32]

Now, we can create an mne.Epochs object with the events we’ve extracted. Note that epochs constructed in this manner will not have their data available until explicitly read into memory, which you can do with get_data. Alternatively, you can use preload=True.

Note that there are many options available when loading an mne.Epochs object. For more detailed information, see (LINK TO EPOCHS LOADING TUTORIAL)

# Expose the raw data as epochs, cut from -0.1 s to 1.0 s relative to the event
# onsets
epochs = mne.Epochs(raw, events, event_id, tmin=-0.1, tmax=1,
                    baseline=(None, 0), preload=True)
print(epochs)

Out:

<Epochs  |  n_events : 145 (all good), tmin : -0.0998976065792 (s), tmax : 1.0006410259 (s), baseline : (None, 0),
 'left': 72, 'right': 73>

Epochs behave similarly to mne.io.Raw objects. They have an info attribute that has all of the same information, as well as a number of attributes unique to the events contained within the object.

print(epochs.events[:3], epochs.event_id, sep='\n\n')

Out:

[[27977     0     2]
 [28771     0     1]
 [29652     0     2]]

{'right': 2, 'left': 1}

You can select subsets of epochs by indexing the Epochs object directly. Alternatively, if you have epoch names specified in event_id then you may index with strings instead.

print(epochs[1:5])
print(epochs['right'])

Out:

<Epochs  |  n_events : 4 (all good), tmin : -0.0998976065792 (s), tmax : 1.0006410259 (s), baseline : (None, 0),
 'left': 2, 'right': 2>
<Epochs  |  n_events : 73 (all good), tmin : -0.0998976065792 (s), tmax : 1.0006410259 (s), baseline : (None, 0)>

It is also possible to iterate through Epochs objects in this way. Note that behavior is different if you iterate on Epochs directly rather than indexing:

# These will be epochs objects
for i in range(3):
    print(epochs[i])

# These will be arrays
for ep in epochs[:2]:
    print(ep)

Out:

<Epochs  |  n_events : 1 (all good), tmin : -0.0998976065792 (s), tmax : 1.0006410259 (s), baseline : (None, 0)>
<Epochs  |  n_events : 1 (all good), tmin : -0.0998976065792 (s), tmax : 1.0006410259 (s), baseline : (None, 0)>
<Epochs  |  n_events : 1 (all good), tmin : -0.0998976065792 (s), tmax : 1.0006410259 (s), baseline : (None, 0)>
[[ -1.56510152e-12  -6.00746037e-13   3.63609444e-13 ...,  -5.42252344e-12
   -3.49381248e-12   8.07845329e-12]
 [  4.71111366e-12   2.78240270e-12  -1.10663744e-13 ...,  -2.03937471e-12
   -1.07501922e-12   1.81804722e-12]
 [  1.27694161e-13   1.26810933e-13   8.74659808e-14 ...,   3.27176412e-14
    5.59107736e-14   6.80975243e-14]
 ...,
 [  1.23131267e-06   7.56233126e-07   3.00980681e-07 ...,  -4.92607996e-06
   -5.29288884e-06  -4.96516158e-06]
 [  2.15536774e-06   2.46614632e-06   2.39846713e-06 ...,  -4.64649509e-06
   -4.75225661e-06  -4.52661069e-06]
 [  1.26772322e-05   1.26772322e-05   1.33309187e-05 ...,  -1.41239155e-05
   -1.41239155e-05  -1.15091693e-05]]
[[ -1.38645862e-11  -1.48289417e-11  -1.48289417e-11 ...,   4.45816796e-12
    4.45816796e-12   8.31558988e-12]
 [ -9.01119056e-12  -1.19042570e-11  -1.28686125e-11 ...,   1.59671973e-12
    3.52543069e-12   3.52543069e-12]
 [ -6.12059507e-13  -6.39043401e-13  -7.73632967e-13 ...,   1.21753954e-14
    2.69203700e-14   7.25978380e-15]
 ...,
 [ -1.26659305e-06  -8.24046269e-07   6.87035679e-08 ...,   2.17776256e-05
    2.13639537e-05   2.18647632e-05]
 [ -7.43371155e-06  -7.56501732e-06  -7.75591614e-06 ...,   1.08169901e-05
    8.21941912e-06   7.93006744e-06]
 [  3.34344584e-06   7.28699735e-07  -3.19341943e-06 ...,   7.50132080e-08
   -5.78673319e-07   3.34344584e-06]]

If you wish to look at the average across trial types, then you may do so, creating an Evoked object in the process.

ev_left = epochs['left'].average()
ev_right = epochs['right'].average()

f, axs = plt.subplots(3, 2, figsize=(10, 5))
_ = f.suptitle('Left / Right', fontsize=20)
_ = ev_left.plot(axes=axs[:, 0], show=False)
_ = ev_right.plot(axes=axs[:, 1], show=False)
plt.tight_layout()
../_images/sphx_glr_plot_epochs_objects_001.png

Total running time of the script: (0 minutes 9.274 seconds)

Download Python source code: plot_epochs_objects.py
Download IPython notebook: plot_epochs_objects.ipynb