Creating MNE’s data structures from scratch

MNE provides mechanisms for creating various core objects directly from NumPy arrays.

import mne
import numpy as np

Creating Info objects

Note

for full documentation on the Info object, see The Info data structure. See also Creating MNE objects from data arrays.

Normally, mne.Info objects are created by the various data import functions. However, if you wish to create one from scratch, you can use the mne.create_info() function to initialize the minimally required fields. Further fields can be assigned later as one would with a regular dictionary.

The following creates the absolute minimum info structure:

# Create some dummy metadata
n_channels = 32
sampling_rate = 200
info = mne.create_info(n_channels, sampling_rate)
print(info)

Out:

<Info | 16 non-empty fields
    bads : list | 0 items
    ch_names : list | 0, 1, 2, 3, 4, 5, 6, 7, 8, ...
    chs : list | 32 items (MISC: 32)
    comps : list | 0 items
    custom_ref_applied : bool | False
    dev_head_t : Transform | 3 items
    events : list | 0 items
    highpass : float | 0.0 Hz
    hpi_meas : list | 0 items
    hpi_results : list | 0 items
    lowpass : float | 100.0 Hz
    meas_date : ndarray | 1970-01-01 00:00:00 GMT
    nchan : int | 32
    proc_history : list | 0 items
    projs : list | 0 items
    sfreq : float | 200.0 Hz
    acq_pars : NoneType
    acq_stim : NoneType
    buffer_size_sec : NoneType
    ctf_head_t : NoneType
    description : NoneType
    dev_ctf_t : NoneType
    dig : NoneType
    experimenter : NoneType
    file_id : NoneType
    hpi_subsystem : NoneType
    kit_system_id : NoneType
    line_freq : NoneType
    meas_id : NoneType
    proj_id : NoneType
    proj_name : NoneType
    subject_info : NoneType
    xplotter_layout : NoneType
>

You can also supply more extensive metadata:

# Names for each channel
channel_names = ['MEG1', 'MEG2', 'Cz', 'Pz', 'EOG']

# The type (mag, grad, eeg, eog, misc, ...) of each channel
channel_types = ['grad', 'grad', 'eeg', 'eeg', 'eog']

# The sampling rate of the recording
sfreq = 1000  # in Hertz

# The EEG channels use the standard naming strategy.
# By supplying the 'montage' parameter, approximate locations
# will be added for them
montage = 'standard_1005'

# Initialize required fields
info = mne.create_info(channel_names, sfreq, channel_types, montage)

# Add some more information
info['description'] = 'My custom dataset'
info['bads'] = ['Pz']  # Names of bad channels

print(info)

Out:

<Info | 18 non-empty fields
    bads : list | Pz
    ch_names : list | MEG1, MEG2, Cz, Pz, EOG
    chs : list | 5 items (EOG: 1, EEG: 2, GRAD: 2)
    comps : list | 0 items
    custom_ref_applied : bool | False
    description : str | 17 items
    dev_head_t : Transform | 3 items
    dig : list | 5 items
    events : list | 0 items
    highpass : float | 0.0 Hz
    hpi_meas : list | 0 items
    hpi_results : list | 0 items
    lowpass : float | 500.0 Hz
    meas_date : ndarray | 1970-01-01 00:00:00 GMT
    nchan : int | 5
    proc_history : list | 0 items
    projs : list | 0 items
    sfreq : float | 1000.0 Hz
    acq_pars : NoneType
    acq_stim : NoneType
    buffer_size_sec : NoneType
    ctf_head_t : NoneType
    dev_ctf_t : NoneType
    experimenter : NoneType
    file_id : NoneType
    hpi_subsystem : NoneType
    kit_system_id : NoneType
    line_freq : NoneType
    meas_id : NoneType
    proj_id : NoneType
    proj_name : NoneType
    subject_info : NoneType
    xplotter_layout : NoneType
>

Note

When assigning new values to the fields of an mne.Info object, it is important that the fields are consistent:

  • The length of the channel information field chs must be nchan.
  • The length of the ch_names field must be nchan.
  • The ch_names field should be consistent with the name field of the channel information contained in chs.

Creating Raw objects

To create a mne.io.Raw object from scratch, you can use the mne.io.RawArray class, which implements raw data that is backed by a numpy array. The correct units for the data are:

  • V: eeg, eog, seeg, emg, ecg, bio, ecog
  • T: mag
  • T/m: grad
  • M: hbo, hbr
  • Am: dipole
  • AU: misc

The mne.io.RawArray constructor simply takes the data matrix and mne.Info object:

# Generate some random data
data = np.random.randn(5, 1000)

# Initialize an info structure
info = mne.create_info(
    ch_names=['MEG1', 'MEG2', 'EEG1', 'EEG2', 'EOG'],
    ch_types=['grad', 'grad', 'eeg', 'eeg', 'eog'],
    sfreq=100
)

custom_raw = mne.io.RawArray(data, info)
print(custom_raw)

Out:

<RawArray  |  None, n_channels x n_times : 5 x 1000 (10.0 sec), ~55 kB, data loaded>

Creating Epochs objects

To create an mne.Epochs object from scratch, you can use the mne.EpochsArray class, which uses a numpy array directly without wrapping a raw object. The array must be of shape(n_epochs, n_chans, n_times). The proper units of measure are listed above.

# Generate some random data: 10 epochs, 5 channels, 2 seconds per epoch
sfreq = 100
data = np.random.randn(10, 5, sfreq * 2)

# Initialize an info structure
info = mne.create_info(
    ch_names=['MEG1', 'MEG2', 'EEG1', 'EEG2', 'EOG'],
    ch_types=['grad', 'grad', 'eeg', 'eeg', 'eog'],
    sfreq=sfreq
)

It is necessary to supply an “events” array in order to create an Epochs object. This is of shape(n_events, 3) where the first column is the sample number (time) of the event, the second column indicates the value from which the transition is made from (only used when the new value is bigger than the old one), and the third column is the new event value.

# Create an event matrix: 10 events with alternating event codes
events = np.array([
    [0, 0, 1],
    [1, 0, 2],
    [2, 0, 1],
    [3, 0, 2],
    [4, 0, 1],
    [5, 0, 2],
    [6, 0, 1],
    [7, 0, 2],
    [8, 0, 1],
    [9, 0, 2],
])

More information about the event codes: subject was either smiling or frowning

event_id = dict(smiling=1, frowning=2)

Finally, we must specify the beginning of an epoch (the end will be inferred from the sampling frequency and n_samples)

# Trials were cut from -0.1 to 1.0 seconds
tmin = -0.1

Now we can create the mne.EpochsArray object

custom_epochs = mne.EpochsArray(data, info, events, tmin, event_id)

print(custom_epochs)

# We can treat the epochs object as we would any other
_ = custom_epochs['smiling'].average().plot()
../_images/sphx_glr_plot_creating_data_structures_001.png

Out:

<EpochsArray  |  n_events : 10 (all good), tmin : -0.1 (s), tmax : 1.89 (s), baseline : None, ~94 kB, data loaded,
 'frowning': 5, 'smiling': 5>

Creating Evoked Objects

If you already have data that is collapsed across trials, you may also directly create an evoked array. Its constructor accepts an array of shape(n_chans, n_times) in addition to some bookkeeping parameters. The proper units of measure for the data are listed above.

# The averaged data
data_evoked = data.mean(0)

# The number of epochs that were averaged
nave = data.shape[0]

# A comment to describe to evoked (usually the condition name)
comment = "Smiley faces"

# Create the Evoked object
evoked_array = mne.EvokedArray(data_evoked, info, tmin,
                               comment=comment, nave=nave)
print(evoked_array)
_ = evoked_array.plot()
../_images/sphx_glr_plot_creating_data_structures_002.png

Out:

<Evoked  |  comment : 'Smiley faces', kind : average, time : [-0.100000, 1.890000], n_epochs : 10, n_channels x n_times : 5 x 200, ~24 kB>

Gallery generated by Sphinx-Gallery