mne.
Epochs
(raw, events, event_id, tmin, tmax, baseline=(None, 0), picks=None, name='Unknown', preload=False, reject=None, flat=None, proj=True, decim=1, reject_tmin=None, reject_tmax=None, detrend=None, add_eeg_ref=True, on_missing='error', verbose=None)¶Epochs extracted from a Raw instance
Parameters: | raw : Raw object
events : array of int, shape (n_events, 3)
event_id : int | list of int | dict | None
tmin : float
tmax : float
baseline : None or tuple of length 2 (default (None, 0))
picks : array-like of int | None (default)
name : string
preload : boolean
reject : dict | None
flat : dict | None
proj : bool | ‘delayed’
decim : int
reject_tmin : scalar | None
reject_tmax : scalar | None
detrend : int | None
add_eeg_ref : bool
on_missing : str
verbose : bool, str, int, or None
|
---|---|
Attributes: | info: dict :
event_id : dict
ch_names : list of string
selection : array
preload : bool
drop_log : list of lists
verbose : bool, str, int, or None
|
Notes
When accessing data, Epochs are detrended, baseline-corrected, and decimated, then projectors are (optionally) applied.
For indexing and slicing:
For subset selection using categorial labels:
Return Epochs object with a subset of epochs corresponding to an experimental condition as specified by ‘name’.
If conditions are tagged by names separated by ‘/’ (e.g. ‘audio/left’, ‘audio/right’), and ‘name’ is not in itself an event key, this selects every event whose condition contains the ‘name’ tag (e.g., ‘left’ matches ‘audio/left’ and ‘visual/left’; but not ‘audio_left’). Note that tags like ‘auditory/left’ and ‘left/auditory’ will be treated the same way when accessed using tags.
Return Epochs object with a subset of epochs corresponding to multiple experimental conditions as specified by ‘name_1’, ‘name_2’, ... .
If conditions are separated by ‘/’, selects every item containing every list tag (e.g. [‘audio’, ‘left’] selects ‘audio/left’ and ‘audio/center/left’, but not ‘audio/right’).
Methods
add_channels (add_list[, copy]) |
Append new channels to the instance. |
add_eeg_average_proj () |
Add an average EEG reference projector if one does not exist |
add_proj (projs[, remove_existing]) |
Add SSP projection vectors |
apply_baseline (baseline[, verbose]) |
Baseline correct epochs |
apply_proj () |
Apply the signal space projection (SSP) operators to the data. |
average ([picks]) |
Compute average of epochs |
copy () |
Return copy of Epochs instance |
crop ([tmin, tmax, copy]) |
Crops a time interval from epochs object. |
decimate (decim[, copy]) |
Decimate the epochs |
del_proj (idx) |
Remove SSP projection vector |
drop_bad_epochs ([reject, flat]) |
Drop bad epochs without retaining the epochs data. |
drop_channels (ch_names[, copy]) |
Drop some channels |
drop_epochs (indices[, reason, verbose]) |
Drop epochs based on indices or boolean mask |
drop_log_stats ([ignore]) |
Compute the channel stats based on a drop_log from Epochs. |
equalize_event_counts (event_ids[, method, copy]) |
Equalize the number of trials in each condition |
get_data () |
Get all epochs as a 3D array |
interpolate_bads ([reset_bads, mode]) |
Interpolate bad MEG and EEG channels. |
iter_evoked () |
Iterate over Evoked objects with nave=1 |
load_data () |
Load the data if not already preloaded |
next ([return_event_id]) |
To make iteration over epochs easy. |
pick_channels (ch_names[, copy]) |
Pick some channels |
pick_types ([meg, eeg, stim, eog, ecg, emg, ...]) |
Pick some channels by type and names |
plot ([picks, scalings, show, block, ...]) |
Visualize epochs. |
plot_drop_log ([threshold, n_max_plot, ...]) |
Show the channel stats based on a drop_log from Epochs |
plot_projs_topomap ([ch_type, layout, axes]) |
Plot SSP vector |
plot_psd ([fmin, fmax, proj, n_fft, picks, ...]) |
Plot the power spectral density across epochs |
plot_psd_topomap ([bands, vmin, vmax, proj, ...]) |
Plot the topomap of the power spectral density across epochs |
rename_channels (mapping) |
Rename channels. |
resample (sfreq[, npad, window, n_jobs, ...]) |
Resample preloaded data |
save (fname[, split_size]) |
Save epochs in a fif file |
savgol_filter (h_freq) |
Filter the data using Savitzky-Golay polynomial method |
set_channel_types (mapping) |
Define the sensor type of channels. |
set_montage (montage) |
Set EEG sensor configuration |
standard_error ([picks]) |
Compute standard error over epochs |
subtract_evoked ([evoked]) |
Subtract an evoked response from each epoch |
to_data_frame ([picks, index, scale_time, ...]) |
Export data in tabular structure as a pandas DataFrame. |
__init__
(raw, events, event_id, tmin, tmax, baseline=(None, 0), picks=None, name='Unknown', preload=False, reject=None, flat=None, proj=True, decim=1, reject_tmin=None, reject_tmax=None, detrend=None, add_eeg_ref=True, on_missing='error', verbose=None)¶add_channels
(add_list, copy=False)¶Append new channels to the instance.
Parameters: | add_list : list
copy : bool
|
---|---|
Returns: | out : MNE object of type(self)
|
add_eeg_average_proj
()¶Add an average EEG reference projector if one does not exist
add_proj
(projs, remove_existing=False)¶Add SSP projection vectors
Parameters: | projs : list
remove_existing : bool
|
---|---|
Returns: | self : instance of Raw | Epochs | Evoked
|
apply_baseline
(baseline, verbose=None)¶Baseline correct epochs
Parameters: | baseline : tuple of length 2
verbose : bool, str, int, or None
|
---|---|
Returns: | epochs : instance of Epochs
|
Notes
Baseline correction can be done multiple times.
New in version 0.10.0.
apply_proj
()¶Apply the signal space projection (SSP) operators to the data.
Returns: | self : instance of Raw | Epochs | Evoked
|
---|
Notes
Once the projectors have been applied, they can no longer be removed. It is usually not recommended to apply the projectors at too early stages, as they are applied automatically later on (e.g. when computing inverse solutions). Hint: using the copy method individual projection vectors can be tested without affecting the original data. With evoked data, consider the following example:
projs_a = mne.read_proj('proj_a.fif')
projs_b = mne.read_proj('proj_b.fif')
# add the first, copy, apply and see ...
evoked.add_proj(a).copy().apply_proj().plot()
# add the second, copy, apply and see ...
evoked.add_proj(b).copy().apply_proj().plot()
# drop the first and see again
evoked.copy().del_proj(0).apply_proj().plot()
evoked.apply_proj() # finally keep both
average
(picks=None)¶Compute average of epochs
Parameters: | picks : array-like of int | None
|
---|---|
Returns: | evoked : instance of Evoked
|
ch_names
¶Channel names
copy
()¶Return copy of Epochs instance
crop
(tmin=None, tmax=None, copy=False)¶Crops a time interval from epochs object.
Parameters: | tmin : float | None
tmax : float | None
copy : bool
|
---|---|
Returns: | epochs : Epochs instance
|
Notes
Unlike Python slices, MNE time intervals include both their end points; crop(tmin, tmax) returns the interval tmin <= t <= tmax.
decimate
(decim, copy=False)¶Decimate the epochs
Parameters: | decim : int
copy : bool
|
---|---|
Returns: | epochs : instance of Epochs
|
Notes
Decimation can be done multiple times. For example,
epochs.decimate(2).decimate(2)
will be the same as
epochs.decimate(4)
.
New in version 0.10.0.
del_proj
(idx)¶Remove SSP projection vector
Parameters: | idx : int
|
---|---|
Returns: | self : instance of Raw | Epochs | Evoked |
drop_bad_epochs
(reject='existing', flat='existing')¶Drop bad epochs without retaining the epochs data.
Should be used before slicing operations.
Warning
Operation is slow since all epochs have to be read from disk. To avoid reading epochs from disk multiple times, initialize Epochs object with preload=True.
Parameters: | reject : dict | str | None
flat : dict | str | None
|
---|
Notes
Dropping bad epochs can be done multiple times with different
reject
and flat
parameters. However, once an epoch is
dropped, it is dropped forever, so if more lenient thresholds may
subsequently be applied, epochs.copy should be used.
drop_channels
(ch_names, copy=False)¶Drop some channels
Parameters: | ch_names : list
copy : bool
|
---|
See also
Notes
New in version 0.9.0.
drop_epochs
(indices, reason='USER', verbose=None)¶Drop epochs based on indices or boolean mask
Note that the indices refer to the current set of undropped epochs rather than the complete set of dropped and undropped epochs. They are therefore not necessarily consistent with any external indices (e.g., behavioral logs). To drop epochs based on external criteria, do not use the preload=True flag when constructing an Epochs object, and call this method before calling the drop_bad_epochs method.
Parameters: | indices : array of ints or bools
reason : str
verbose : bool, str, int, or None
|
---|
drop_log_stats
(ignore=('IGNORED', ))¶Compute the channel stats based on a drop_log from Epochs.
Parameters: | ignore : list
|
---|---|
Returns: | perc : float
|
See also
equalize_event_counts
(event_ids, method='mintime', copy=True)¶Equalize the number of trials in each condition
It tries to make the remaining epochs occurring as close as possible in time. This method works based on the idea that if there happened to be some time-varying (like on the scale of minutes) noise characteristics during a recording, they could be compensated for (to some extent) in the equalization process. This method thus seeks to reduce any of those effects by minimizing the differences in the times of the events in the two sets of epochs. For example, if one had event times [1, 2, 3, 4, 120, 121] and the other one had [3.5, 4.5, 120.5, 121.5], it would remove events at times [1, 2] in the first epochs and not [20, 21].
Parameters: | event_ids : list
method : str
copy : bool
|
---|---|
Returns: | epochs : instance of Epochs
indices : array of int
|
Notes
For example (if epochs.event_id was {‘Left’: 1, ‘Right’: 2, ‘Nonspatial’:3}:
epochs.equalize_event_counts([[‘Left’, ‘Right’], ‘Nonspatial’])
would equalize the number of trials in the ‘Nonspatial’ condition with the total number of trials in the ‘Left’ and ‘Right’ conditions.
If multiple indices are provided (e.g. ‘Left’ and ‘Right’ in the example above), it is not guaranteed that after equalization, the conditions will contribute evenly. E.g., it is possible to end up with 70 ‘Nonspatial’ trials, 69 ‘Left’ and 1 ‘Right’.
get_data
()¶Get all epochs as a 3D array
Returns: | data : array of shape (n_epochs, n_channels, n_times)
|
---|
interpolate_bads
(reset_bads=True, mode='accurate')¶Interpolate bad MEG and EEG channels.
Operates in place.
Parameters: | reset_bads : bool
mode : str
|
---|---|
Returns: | self : mne.io.Raw, mne.Epochs or mne.Evoked
|
Notes
New in version 0.9.0.
iter_evoked
()¶Iterate over Evoked objects with nave=1
load_data
()¶Load the data if not already preloaded
Returns: | epochs : instance of Epochs
|
---|
Notes
This function operates in-place.
New in version 0.10.0.
next
(return_event_id=False)¶To make iteration over epochs easy.
Parameters: | return_event_id : bool
|
---|---|
Returns: | epoch : instance of Epochs
event_id : int
|
pick_channels
(ch_names, copy=False)¶Pick some channels
Parameters: | ch_names : list
copy : bool
|
---|
See also
Notes
New in version 0.9.0.
pick_types
(meg=True, eeg=False, stim=False, eog=False, ecg=False, emg=False, ref_meg='auto', misc=False, resp=False, chpi=False, exci=False, ias=False, syst=False, seeg=False, include=[], exclude='bads', selection=None, copy=False)¶Pick some channels by type and names
Parameters: | meg : bool | str
eeg : bool
stim : bool
eog : bool
ecg : bool
emg : bool
ref_meg: bool | str :
misc : bool
resp : bool
chpi : bool
exci : bool
ias : bool
syst : bool
seeg : bool
include : list of string
exclude : list of string | str
selection : list of string
copy : bool
|
---|
Notes
New in version 0.9.0.
plot
(picks=None, scalings=None, show=True, block=False, n_epochs=20, n_channels=20, title=None)¶Visualize epochs.
Bad epochs can be marked with a left click on top of the epoch. Bad channels can be selected by clicking the channel name on the left side of the main axes. Calling this function drops all the selected bad epochs as well as bad epochs marked beforehand with rejection parameters.
Parameters: | picks : array-like of int | None
scalings : dict | None
show : bool
block : bool
n_epochs : int
n_channels : int
title : str | None
|
---|---|
Returns: | fig : Instance of matplotlib.figure.Figure
|
Notes
The arrow keys (up/down/left/right) can
be used to navigate between channels and epochs and the scaling can be
adjusted with - and + (or =) keys, but this depends on the backend
matplotlib is configured to use (e.g., mpl.use(TkAgg
) should work).
Full screen mode can be toggled with f11 key. The amount of epochs
and channels per view can be adjusted with home/end and
page down/page up keys. Butterfly plot can be toggled with b
key.
Right mouse click adds a vertical line to the plot.
New in version 0.10.0.
plot_drop_log
(threshold=0, n_max_plot=20, subject='Unknown', color=(0.9, 0.9, 0.9), width=0.8, ignore=('IGNORED', ), show=True)¶Show the channel stats based on a drop_log from Epochs
Parameters: | threshold : float
n_max_plot : int
subject : str
color : tuple | str
width : float
ignore : list
show : bool
|
---|---|
Returns: | perc : float
fig : Instance of matplotlib.figure.Figure
|
plot_projs_topomap
(ch_type=None, layout=None, axes=None)¶Plot SSP vector
Parameters: | ch_type : ‘mag’ | ‘grad’ | ‘planar1’ | ‘planar2’ | ‘eeg’ | None | List
layout : None | Layout | List of Layouts
axes : instance of Axes | list | None
|
---|---|
Returns: | fig : instance of matplotlib figure
|
plot_psd
(fmin=0, fmax=inf, proj=False, n_fft=256, picks=None, ax=None, color='black', area_mode='std', area_alpha=0.33, n_overlap=0, dB=True, n_jobs=1, verbose=None, show=True)¶Plot the power spectral density across epochs
Parameters: | fmin : float
fmax : float
proj : bool
n_fft : int
picks : array-like of int | None
ax : instance of matplotlib Axes | None
color : str | tuple
area_mode : str | None
area_alpha : float
n_overlap : int
dB : bool
n_jobs : int
verbose : bool, str, int, or None
show : bool
|
---|---|
Returns: | fig : instance of matplotlib figure
|
plot_psd_topomap
(bands=None, vmin=None, vmax=None, proj=False, n_fft=256, ch_type=None, n_overlap=0, layout=None, cmap='RdBu_r', agg_fun=None, dB=True, n_jobs=1, normalize=False, cbar_fmt='%0.3f', outlines='head', show=True, verbose=None)¶Plot the topomap of the power spectral density across epochs
Parameters: | bands : list of tuple | None
vmin : float | callable | None
vmax : float | callable | None
proj : bool
n_fft : int
ch_type : {None, ‘mag’, ‘grad’, ‘planar1’, ‘planar2’, ‘eeg’}
n_overlap : int
layout : None | Layout
cmap : matplotlib colormap
agg_fun : callable
dB : bool
n_jobs : int
normalize : bool
cbar_fmt : str
outlines : ‘head’ | ‘skirt’ | dict | None
show : bool
verbose : bool, str, int, or None
|
---|---|
Returns: | fig : instance of matplotlib figure
|
rename_channels
(mapping)¶Rename channels.
Parameters: | mapping : dict | callable
|
---|
Notes
New in version 0.9.0.
resample
(sfreq, npad=100, window='boxcar', n_jobs=1, copy=False, verbose=None)¶Resample preloaded data
Parameters: | sfreq : float
npad : int
window : string or tuple
n_jobs : int
copy : bool
verbose : bool, str, int, or None
|
---|---|
Returns: | epochs : instance of Epochs
|
Notes
For some data, it may be more accurate to use npad=0 to reduce artifacts. This is dataset dependent – check your data!
save
(fname, split_size='2GB')¶Save epochs in a fif file
Parameters: | fname : str
split_size : string | int
|
---|
Notes
Bad epochs will be dropped before saving the epochs to disk.
savgol_filter
(h_freq)¶Filter the data using Savitzky-Golay polynomial method
Parameters: | h_freq : float
|
---|
See also
mne.io.Raw.filter
Notes
Data are modified in-place.
For Savitzky-Golay low-pass approximation, see:
New in version 0.9.0.
References
[R1] | (1, 2) Savitzky, A., Golay, M.J.E. (1964). “Smoothing and Differentiation of Data by Simplified Least Squares Procedures”. Analytical Chemistry 36 (8): 1627-39. |
Examples
>>> import mne
>>> from os import path as op
>>> evoked_fname = op.join(mne.datasets.sample.data_path(), 'MEG', 'sample', 'sample_audvis-ave.fif')
>>> evoked = mne.read_evokeds(evoked_fname, baseline=(None, 0))[0]
>>> evoked.savgol_filter(10.) # low-pass at around 10 Hz
>>> evoked.plot()
set_channel_types
(mapping)¶Define the sensor type of channels.
Parameters: | mapping : dict
|
---|
Notes
New in version 0.9.0.
set_montage
(montage)¶Set EEG sensor configuration
Parameters: | montage : instance of Montage or DigMontage |
---|
Notes
Operates in place.
New in version 0.9.0.
standard_error
(picks=None)¶Compute standard error over epochs
Parameters: | picks : array-like of int | None
|
---|---|
Returns: | evoked : instance of Evoked
|
subtract_evoked
(evoked=None)¶Subtract an evoked response from each epoch
Can be used to exclude the evoked response when analyzing induced activity, see e.g. [1].
Parameters: | evoked : instance of Evoked | None
|
---|---|
Returns: | self : instance of Epochs
|
References
[1] David et al. “Mechanisms of evoked and induced responses in MEG/EEG”, NeuroImage, vol. 31, no. 4, pp. 1580-1591, July 2006.
to_data_frame
(picks=None, index=None, scale_time=1000.0, scalings=None, copy=True, start=None, stop=None)¶Export data in tabular structure as a pandas DataFrame.
Columns and indices will depend on the object being converted. Generally this will include as much relevant information as possible for the data type being converted. This makes it easy to convert data for use in packages that utilize dataframes, such as statsmodels or seaborn.
Parameters: | picks : array-like of int | None
index : tuple of str | None
scale_time : float
scalings : dict | None
copy : bool
start : int | None
stop : int | None
|
---|---|
Returns: | df : instance of pandas.core.DataFrame
|