Note

Click here to download the full example code

The Evoked data structure: evoked/averaged data

The Evoked data structure is mainly used for storing averaged data over trials. In MNE the evoked objects are usually created by averaging epochs data with mne.Epochs.average().

import os.path as op

import matplotlib.pyplot as plt
import mne

Here for convenience we read the evoked dataset from a file.

data_path = mne.datasets.sample.data_path()
fname = op.join(data_path, 'MEG', 'sample', 'sample_audvis-ave.fif')
evokeds = mne.read_evokeds(fname, baseline=(None, 0), proj=True)
print(evokeds)

Out:

Reading /home/circleci/mne_data/MNE-sample-data/MEG/sample/sample_audvis-ave.fif ...
    Read a total of 4 projection items:
        PCA-v1 (1 x 102) active
        PCA-v2 (1 x 102) active
        PCA-v3 (1 x 102) active
        Average EEG reference (1 x 60) active
    Found the data of interest:
        t =    -199.80 ...     499.49 ms (Left Auditory)
        0 CTF compensation matrices available
        nave = 55 - aspect type = 100
Projections have already been applied. Setting proj attribute to True.
Applying baseline correction (mode: mean)
    Read a total of 4 projection items:
        PCA-v1 (1 x 102) active
        PCA-v2 (1 x 102) active
        PCA-v3 (1 x 102) active
        Average EEG reference (1 x 60) active
    Found the data of interest:
        t =    -199.80 ...     499.49 ms (Right Auditory)
        0 CTF compensation matrices available
        nave = 61 - aspect type = 100
Projections have already been applied. Setting proj attribute to True.
Applying baseline correction (mode: mean)
    Read a total of 4 projection items:
        PCA-v1 (1 x 102) active
        PCA-v2 (1 x 102) active
        PCA-v3 (1 x 102) active
        Average EEG reference (1 x 60) active
    Found the data of interest:
        t =    -199.80 ...     499.49 ms (Left visual)
        0 CTF compensation matrices available
        nave = 67 - aspect type = 100
Projections have already been applied. Setting proj attribute to True.
Applying baseline correction (mode: mean)
    Read a total of 4 projection items:
        PCA-v1 (1 x 102) active
        PCA-v2 (1 x 102) active
        PCA-v3 (1 x 102) active
        Average EEG reference (1 x 60) active
    Found the data of interest:
        t =    -199.80 ...     499.49 ms (Right visual)
        0 CTF compensation matrices available
        nave = 58 - aspect type = 100
Projections have already been applied. Setting proj attribute to True.
Applying baseline correction (mode: mean)
[<Evoked  |  'Left Auditory' (average, N=55), [-0.1998, 0.49949] sec, 376 ch, ~4.9 MB>, <Evoked  |  'Right Auditory' (average, N=61), [-0.1998, 0.49949] sec, 376 ch, ~4.9 MB>, <Evoked  |  'Left visual' (average, N=67), [-0.1998, 0.49949] sec, 376 ch, ~4.9 MB>, <Evoked  |  'Right visual' (average, N=58), [-0.1998, 0.49949] sec, 376 ch, ~4.9 MB>]

Notice that the reader function returned a list of evoked instances. This is because you can store multiple categories into a single file. Here we have categories of ['Left Auditory', 'Right Auditory', 'Left Visual', 'Right Visual']. We can also use condition parameter to read in only one category.

evoked = mne.read_evokeds(fname, condition='Left Auditory')
evoked.apply_baseline((None, 0)).apply_proj()
print(evoked)

Out:

Reading /home/circleci/mne_data/MNE-sample-data/MEG/sample/sample_audvis-ave.fif ...
    Read a total of 4 projection items:
        PCA-v1 (1 x 102) active
        PCA-v2 (1 x 102) active
        PCA-v3 (1 x 102) active
        Average EEG reference (1 x 60) active
    Found the data of interest:
        t =    -199.80 ...     499.49 ms (Left Auditory)
        0 CTF compensation matrices available
        nave = 55 - aspect type = 100
Projections have already been applied. Setting proj attribute to True.
No baseline correction applied
Applying baseline correction (mode: mean)
Projections have already been applied. Setting proj attribute to True.
<Evoked  |  'Left Auditory' (average, N=55), [-0.1998, 0.49949] sec, 376 ch, ~4.9 MB>

If you’re gone through the tutorials of raw and epochs datasets, you’re probably already familiar with the Info attribute. There is nothing new or special with the evoked.info. All the relevant info is still there.

print(evoked.info)
print(evoked.times)

Out:

<Info | 20 non-empty fields
    bads : list | MEG 2443, EEG 053
    ch_names : list | MEG 0113, MEG 0112, MEG 0111, MEG 0122, MEG 0123, ...
    chs : list | 376 items (GRAD: 204, MAG: 102, STIM: 9, EEG: 60, EOG: 1)
    comps : list | 0 items
    custom_ref_applied : bool | False
    dev_head_t : Transform | 3 items
    dig : Digitization | 146 items (3 Cardinal, 4 HPI, 61 EEG, 78 Extra)
    events : list | 0 items
    file_id : dict | 4 items
    highpass : float | 0.10000000149011612 Hz
    hpi_meas : list | 1 items
    hpi_results : list | 1 items
    lowpass : float | 40.0 Hz
    maxshield : bool | False
    meas_date : tuple | 2002-12-03 19:01:10 GMT
    meas_id : dict | 4 items
    nchan : int | 376
    proc_history : list | 0 items
    projs : list | PCA-v1: on, PCA-v2: on, PCA-v3: on, ...
    sfreq : float | 600.614990234375 Hz
    acq_pars : NoneType
    acq_stim : NoneType
    ctf_head_t : NoneType
    description : NoneType
    dev_ctf_t : NoneType
    device_info : NoneType
    experimenter : NoneType
    gantry_angle : NoneType
    helium_info : NoneType
    hpi_subsystem : NoneType
    kit_system_id : NoneType
    line_freq : NoneType
    proj_id : NoneType
    proj_name : NoneType
    subject_info : NoneType
    utc_offset : NoneType
    xplotter_layout : NoneType
>
[-0.19979521 -0.19813025 -0.19646529 -0.19480033 -0.19313537 -0.19147041
 -0.18980545 -0.18814049 -0.18647553 -0.18481057 -0.18314561 -0.18148065
 -0.17981569 -0.17815073 -0.17648577 -0.17482081 -0.17315585 -0.17149089
 -0.16982593 -0.16816097 -0.16649601 -0.16483105 -0.16316609 -0.16150113
 -0.15983617 -0.15817121 -0.15650625 -0.15484129 -0.15317633 -0.15151137
 -0.14984641 -0.14818145 -0.14651649 -0.14485153 -0.14318657 -0.14152161
 -0.13985665 -0.13819169 -0.13652673 -0.13486177 -0.13319681 -0.13153185
 -0.12986689 -0.12820193 -0.12653697 -0.12487201 -0.12320705 -0.12154209
 -0.11987713 -0.11821217 -0.11654721 -0.11488225 -0.11321729 -0.11155233
 -0.10988737 -0.10822241 -0.10655745 -0.10489249 -0.10322753 -0.10156257
 -0.09989761 -0.09823265 -0.09656769 -0.09490273 -0.09323777 -0.09157281
 -0.08990785 -0.08824289 -0.08657793 -0.08491297 -0.08324801 -0.08158305
 -0.07991809 -0.07825313 -0.07658817 -0.0749232  -0.07325824 -0.07159328
 -0.06992832 -0.06826336 -0.0665984  -0.06493344 -0.06326848 -0.06160352
 -0.05993856 -0.0582736  -0.05660864 -0.05494368 -0.05327872 -0.05161376
 -0.0499488  -0.04828384 -0.04661888 -0.04495392 -0.04328896 -0.041624
 -0.03995904 -0.03829408 -0.03662912 -0.03496416 -0.0332992  -0.03163424
 -0.02996928 -0.02830432 -0.02663936 -0.0249744  -0.02330944 -0.02164448
 -0.01997952 -0.01831456 -0.0166496  -0.01498464 -0.01331968 -0.01165472
 -0.00998976 -0.0083248  -0.00665984 -0.00499488 -0.00332992 -0.00166496
  0.          0.00166496  0.00332992  0.00499488  0.00665984  0.0083248
  0.00998976  0.01165472  0.01331968  0.01498464  0.0166496   0.01831456
  0.01997952  0.02164448  0.02330944  0.0249744   0.02663936  0.02830432
  0.02996928  0.03163424  0.0332992   0.03496416  0.03662912  0.03829408
  0.03995904  0.041624    0.04328896  0.04495392  0.04661888  0.04828384
  0.0499488   0.05161376  0.05327872  0.05494368  0.05660864  0.0582736
  0.05993856  0.06160352  0.06326848  0.06493344  0.0665984   0.06826336
  0.06992832  0.07159328  0.07325824  0.0749232   0.07658817  0.07825313
  0.07991809  0.08158305  0.08324801  0.08491297  0.08657793  0.08824289
  0.08990785  0.09157281  0.09323777  0.09490273  0.09656769  0.09823265
  0.09989761  0.10156257  0.10322753  0.10489249  0.10655745  0.10822241
  0.10988737  0.11155233  0.11321729  0.11488225  0.11654721  0.11821217
  0.11987713  0.12154209  0.12320705  0.12487201  0.12653697  0.12820193
  0.12986689  0.13153185  0.13319681  0.13486177  0.13652673  0.13819169
  0.13985665  0.14152161  0.14318657  0.14485153  0.14651649  0.14818145
  0.14984641  0.15151137  0.15317633  0.15484129  0.15650625  0.15817121
  0.15983617  0.16150113  0.16316609  0.16483105  0.16649601  0.16816097
  0.16982593  0.17149089  0.17315585  0.17482081  0.17648577  0.17815073
  0.17981569  0.18148065  0.18314561  0.18481057  0.18647553  0.18814049
  0.18980545  0.19147041  0.19313537  0.19480033  0.19646529  0.19813025
  0.19979521  0.20146017  0.20312513  0.20479009  0.20645505  0.20812001
  0.20978497  0.21144993  0.21311489  0.21477985  0.21644481  0.21810977
  0.21977473  0.22143969  0.22310465  0.22476961  0.22643457  0.22809954
  0.2297645   0.23142946  0.23309442  0.23475938  0.23642434  0.2380893
  0.23975426  0.24141922  0.24308418  0.24474914  0.2464141   0.24807906
  0.24974402  0.25140898  0.25307394  0.2547389   0.25640386  0.25806882
  0.25973378  0.26139874  0.2630637   0.26472866  0.26639362  0.26805858
  0.26972354  0.2713885   0.27305346  0.27471842  0.27638338  0.27804834
  0.2797133   0.28137826  0.28304322  0.28470818  0.28637314  0.2880381
  0.28970306  0.29136802  0.29303298  0.29469794  0.2963629   0.29802786
  0.29969282  0.30135778  0.30302274  0.3046877   0.30635266  0.30801762
  0.30968258  0.31134754  0.3130125   0.31467746  0.31634242  0.31800738
  0.31967234  0.3213373   0.32300226  0.32466722  0.32633218  0.32799714
  0.3296621   0.33132706  0.33299202  0.33465698  0.33632194  0.3379869
  0.33965186  0.34131682  0.34298178  0.34464674  0.3463117   0.34797666
  0.34964162  0.35130658  0.35297154  0.3546365   0.35630146  0.35796642
  0.35963138  0.36129634  0.3629613   0.36462626  0.36629122  0.36795618
  0.36962114  0.3712861   0.37295106  0.37461602  0.37628098  0.37794594
  0.37961091  0.38127587  0.38294083  0.38460579  0.38627075  0.38793571
  0.38960067  0.39126563  0.39293059  0.39459555  0.39626051  0.39792547
  0.39959043  0.40125539  0.40292035  0.40458531  0.40625027  0.40791523
  0.40958019  0.41124515  0.41291011  0.41457507  0.41624003  0.41790499
  0.41956995  0.42123491  0.42289987  0.42456483  0.42622979  0.42789475
  0.42955971  0.43122467  0.43288963  0.43455459  0.43621955  0.43788451
  0.43954947  0.44121443  0.44287939  0.44454435  0.44620931  0.44787427
  0.44953923  0.45120419  0.45286915  0.45453411  0.45619907  0.45786403
  0.45952899  0.46119395  0.46285891  0.46452387  0.46618883  0.46785379
  0.46951875  0.47118371  0.47284867  0.47451363  0.47617859  0.47784355
  0.47950851  0.48117347  0.48283843  0.48450339  0.48616835  0.48783331
  0.48949827  0.49116323  0.49282819  0.49449315  0.49615811  0.49782307
  0.49948803]

The evoked data structure also contains some new attributes easily accessible:

print(evoked.nave)  # Number of averaged epochs.
print(evoked.first)  # First time sample.
print(evoked.last)  # Last time sample.
print(evoked.comment)  # Comment on dataset. Usually the condition.
print(evoked.kind)  # Type of data, either average or standard_error.

Out:

55
-120
300
Left Auditory
average

The data is also easily accessible. Since the evoked data arrays are usually much smaller than raw or epochs datasets, they are preloaded into the memory when the evoked object is constructed. You can access the data as a numpy array.

data = evoked.data
print(data.shape)

Out:

(376, 421)

The data is arranged in an array of shape (n_channels, n_times). Notice that unlike epochs, evoked object does not support indexing. This means that to access the data of a specific channel you must use the data array directly.

print('Data from channel {0}:'.format(evoked.ch_names[10]))
print(data[10])

Out:

Data from channel MEG 0142:
[-5.23565064e-13 -4.71585139e-13 -3.86683209e-13 -2.83273649e-13
 -1.77306112e-13 -8.40611219e-14 -1.61924078e-14  1.77381210e-14
  1.40744336e-14 -2.58271015e-14 -9.61522377e-14 -1.87714557e-13
 -2.89375756e-13 -3.89584208e-13 -4.77813276e-13 -5.45725710e-13
 -5.87940404e-13 -6.02348966e-13 -5.89997316e-13 -5.54604288e-13
 -5.01825677e-13 -4.38392525e-13 -3.71250724e-13 -3.06800010e-13
 -2.50310349e-13 -2.05542229e-13 -1.74580799e-13 -1.57849570e-13
 -1.54264699e-13 -1.61491852e-13 -1.76251146e-13 -1.94655758e-13
 -2.12557648e-13 -2.25896541e-13 -2.31046307e-13 -2.25152439e-13
 -2.06448989e-13 -1.74519893e-13 -1.30478919e-13 -7.70193540e-14
 -1.83008226e-14  4.03521585e-14  9.29388774e-14  1.33429445e-13
  1.56509623e-13  1.58334178e-13  1.37187906e-13  9.39425253e-14
  3.22229137e-14 -4.17800040e-14 -1.19859868e-13 -1.92671983e-13
 -2.50842568e-13 -2.86173426e-13 -2.92783887e-13 -2.68019382e-13
 -2.12986679e-13 -1.32611683e-13 -3.51871554e-14  6.85579487e-14
  1.66763009e-13  2.47947716e-13  3.02530649e-13  3.24149315e-13
  3.10581307e-13  2.64139575e-13  1.91462745e-13  1.02720927e-13
  1.03287566e-14 -7.26627789e-14 -1.34281272e-13 -1.65226194e-13
 -1.60116285e-13 -1.18226284e-13 -4.36092726e-14  5.54097285e-14
  1.67298585e-13  2.78793911e-13  3.76588471e-13  4.48998456e-13
  4.87395875e-13  4.87219113e-13  4.48443612e-13  3.75461218e-13
  2.76415294e-13  1.62087994e-13  4.45132094e-14 -6.44960341e-14
 -1.54711526e-13 -2.18570615e-13 -2.51858908e-13 -2.53926201e-13
 -2.27449342e-13 -1.77801407e-13 -1.12146848e-13 -3.84001762e-14
  3.58008409e-14  1.03977395e-13  1.61445919e-13  2.05649837e-13
  2.36181961e-13  2.54522470e-13  2.63571764e-13  2.67051607e-13
  2.68884577e-13  2.72619954e-13  2.80991167e-13  2.95625408e-13
  3.16936487e-13  3.44178221e-13  3.75633015e-13  4.08893096e-13
  4.41194502e-13  4.69755657e-13  4.92097469e-13  5.06313899e-13
  5.11282935e-13  5.06807216e-13  4.93681895e-13  4.73681867e-13
  4.49469792e-13  4.24418784e-13  4.02353520e-13  3.87213731e-13
  3.82662229e-13  3.91664527e-13  4.16082427e-13  4.56330613e-13
  5.11154456e-13  5.77570787e-13  6.51011273e-13  7.25678523e-13
  7.95099727e-13  8.52825900e-13  8.93207072e-13  9.12141741e-13
  9.07702901e-13  8.80534327e-13  8.33944572e-13  7.73666285e-13
  7.07272026e-13  6.43315198e-13  5.90287033e-13  5.55525480e-13
  5.44224439e-13  5.58690011e-13  5.97957357e-13  6.57847998e-13
  7.31476284e-13  8.10156194e-13  8.84600880e-13  9.46254643e-13
  9.88574502e-13  1.00807726e-12  1.00499007e-12  9.83397434e-13
  9.50840173e-13  9.17398638e-13  8.94372859e-13  8.92716238e-13
  9.21443671e-13  9.86219107e-13  1.08833553e-12  1.22422732e-12
  1.38560927e-12  1.56023408e-12  1.73319647e-12  1.88862055e-12
  2.01152581e-12  2.08962862e-12  2.11486154e-12  2.08440814e-12
  2.00110619e-12  1.87319400e-12  1.71340236e-12  1.53751814e-12
  1.36259665e-12  1.20504112e-12  1.07878068e-12  9.93775115e-13
  9.55012122e-13  9.62109576e-13  1.00955776e-12  1.08754957e-12
  1.18328588e-12  1.28257998e-12  1.37155673e-12  1.43824115e-12
  1.47384311e-12  1.47359718e-12  1.43707407e-12  1.36794754e-12
  1.27326637e-12  1.16234419e-12  1.04542210e-12  9.32274111e-13
  8.30941537e-13  7.46741058e-13  6.81670773e-13  6.34267928e-13
  5.99935866e-13  5.71674711e-13  5.41123551e-13  4.99774414e-13
  4.40203914e-13  3.57166739e-13  2.48419283e-13  1.15170557e-13
 -3.78913166e-14 -2.03000897e-13 -3.70094595e-13 -5.27874540e-13
 -6.65031024e-13 -7.71479002e-13 -8.39461228e-13 -8.64396908e-13
 -8.45371742e-13 -7.85221934e-13 -6.90204626e-13 -5.69301044e-13
 -4.33236931e-13 -2.93344145e-13 -1.60393477e-13 -4.35434005e-14
  5.04819854e-14  1.17891112e-13  1.57953568e-13  1.72760525e-13
  1.66659269e-13  1.45453217e-13  1.15476765e-13  8.26756047e-14
  5.18146953e-14  2.59151892e-14  5.99016124e-15 -8.89685393e-15
 -2.12682425e-14 -3.46297138e-14 -5.27233119e-14 -7.87501478e-14
 -1.14684754e-13 -1.60783835e-13 -2.15367722e-13 -2.74908115e-13
 -3.34418383e-13 -3.88090792e-13 -4.30093130e-13 -4.55412599e-13
 -4.60624828e-13 -4.44475585e-13 -4.08188062e-13 -3.55446154e-13
 -2.92046256e-13 -2.25259214e-13 -1.62982264e-13 -1.12791613e-13
 -8.10178973e-14 -7.19678908e-14 -8.73945749e-14 -1.26281955e-13
 -1.84975724e-13 -2.57635654e-13 -3.36953098e-13 -4.15032286e-13
 -4.84326469e-13 -5.38499603e-13 -5.73113386e-13 -5.86050425e-13
 -5.77632389e-13 -5.50426131e-13 -5.08778374e-13 -4.58150576e-13
 -4.04351788e-13 -3.52776159e-13 -3.07748862e-13 -2.72061081e-13
 -2.46751528e-13 -2.31146472e-13 -2.23143154e-13 -2.19677267e-13
 -2.17302409e-13 -2.12785315e-13 -2.03632351e-13 -1.88467661e-13
 -1.67214705e-13 -1.41060149e-13 -1.12212720e-13 -8.35028755e-14
 -5.78867462e-14 -3.79347716e-14 -2.53861604e-14 -2.08334863e-14
 -2.35887818e-14 -3.17473644e-14 -4.24381278e-14 -5.22259943e-14
 -5.75990700e-14 -5.54777566e-14 -4.36592803e-14 -2.11487760e-14
  1.16798141e-14  5.31049618e-14  1.00257101e-13  1.49459440e-13
  1.96659817e-13  2.37887555e-13  2.69671318e-13  2.89362104e-13
  2.95325316e-13  2.86983257e-13  2.64720905e-13  2.29684506e-13
  1.83521713e-13  1.28110148e-13  6.53360301e-14 -3.04685471e-15
 -7.54562181e-14 -1.50414202e-13 -2.26408447e-13 -3.01714358e-13
 -3.74233879e-13 -4.41404448e-13 -5.00216121e-13 -5.47361857e-13
 -5.79519643e-13 -5.93738786e-13 -5.87876290e-13 -5.61020374e-13
 -5.13820836e-13 -4.48667618e-13 -3.69657925e-13 -2.82341748e-13
 -1.93249565e-13 -1.09253600e-13 -3.68349940e-14  1.86446047e-14
  5.35720218e-14  6.65164407e-14  5.84033363e-14  3.23972852e-14
 -6.50200446e-15 -5.20940431e-14 -9.77654042e-14 -1.37316633e-13
 -1.65718982e-13 -1.79691788e-13 -1.78025648e-13 -1.61607341e-13
 -1.33151857e-13 -9.66892395e-14 -5.68891682e-14 -1.83317929e-14
  1.51602091e-14  4.10302853e-14  5.82578888e-14  6.73623633e-14
  7.01465138e-14  6.92389265e-14  6.75196288e-14  6.75415172e-14
  7.10480311e-14  7.86823495e-14  8.99402113e-14  1.03374590e-13
  1.17022657e-13  1.28967475e-13  1.37937400e-13  1.43814668e-13
  1.47955853e-13  1.53234777e-13  1.63782599e-13  1.84435646e-13
  2.19968122e-13  2.74223234e-13  3.49275554e-13  4.44780522e-13
  5.57625480e-13  6.81969209e-13  8.09696537e-13  9.31246736e-13
  1.03672137e-12  1.11711547e-12  1.16551120e-12  1.17804259e-12
  1.15449453e-12  1.09843252e-12  1.01682821e-12  9.19224021e-13
  8.16544850e-13  7.19722944e-13  6.38323538e-13  5.79369223e-13
  5.46529620e-13  5.39785783e-13  5.55614689e-13  5.87656837e-13
  6.27763208e-13  6.67254220e-13  6.98205534e-13  7.14563717e-13
  7.12924662e-13  6.92874971e-13  6.56842603e-13  6.09508183e-13
  5.56870605e-13  5.05132568e-13  4.59588123e-13  4.23692512e-13
  3.98471179e-13  3.82353124e-13  3.71460790e-13  3.60308185e-13
  3.42787112e-13  3.13288342e-13  2.67769464e-13  2.04599607e-13
  1.25039471e-13  3.32753967e-14 -6.40049014e-14 -1.58436924e-13
 -2.41083752e-13]

In the same vein, we can quickly extract (and, e.g., plot) the Global Field Power(GFP) as the standard deviation across channels, here shown just for EEG.

gfp = evoked.copy().pick_types(eeg=True, meg=False).data.std(axis=0)
fig, ax = plt.subplots(1)
ax.plot(evoked.times, gfp / 1e6)  # scale to uV
ax.set(xlabel='Time (sec)', ylabel='GFP (uV)')
fig.tight_layout()
../../_images/sphx_glr_plot_object_evoked_001.png

If you want to import evoked data from some other system and you have it in a numpy array you can use mne.EvokedArray for that. All you need is the data and some info about the evoked data. For more information, see Creating MNE’s data structures from scratch.

evoked = mne.EvokedArray(data, evoked.info, tmin=evoked.times[0])
evoked.plot(time_unit='s')
../../_images/sphx_glr_plot_object_evoked_002.png

To write an evoked dataset to a file, use the mne.Evoked.save() method. To save multiple categories to a single file, see mne.write_evokeds().

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

Estimated memory usage: 8 MB

Gallery generated by Sphinx-Gallery