mne.
Epochs
(raw, events, event_id=None, tmin=-0.2, tmax=0.5, 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', reject_by_annotation=True, 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
reject_by_annotation : bool
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, force_update_info]) |
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, verbose]) |
Add SSP projection vectors |
apply_baseline (baseline[, copy, 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, offset]) |
Decimate the epochs |
del_proj (idx) |
Remove SSP projection vector |
drop (indices[, reason, verbose]) |
Drop epochs based on indices or boolean mask |
drop_bad ([reject, flat, verbose]) |
Drop bad epochs without retaining the epochs data. |
drop_bad_epochs (*args, **kwargs) |
Warning DEPRECATED: drop_bad_epochs method has been renamed drop_bad. drop_bad_epochs method will be removed in 0.13 |
drop_channels (ch_names[, copy]) |
Drop some channels |
drop_epochs (*args, **kwargs) |
Warning DEPRECATED: drop_epochs method has been renamed drop. drop_epochs method will be removed in 0.13 |
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 epochs as a sequence of Evoked objects |
load_data () |
Load the data if not already preloaded |
next ([return_event_id]) |
Iterate over epoch data. |
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_image ([picks, sigma, vmin, vmax, ...]) |
Plot Event Related Potential / Fields image |
plot_projs_topomap ([ch_type, layout, axes]) |
Plot SSP vector |
plot_psd ([fmin, fmax, proj, bandwidth, ...]) |
Plot the power spectral density across epochs |
plot_psd_topomap ([bands, vmin, vmax, proj, ...]) |
Plot the topomap of the power spectral density across epochs |
plot_sensors ([kind, ch_type, title, ...]) |
Plot sensors positions. |
plot_topo_image ([layout, sigma, vmin, vmax, ...]) |
Plot Event Related Potential / Fields image on topographies |
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[, copy]) |
Filter the data using Savitzky-Golay polynomial method |
set_channel_types (mapping) |
Define the sensor type of channels. |
set_montage (montage[, verbose]) |
Set EEG sensor configuration |
standard_error ([picks]) |
Compute standard error over epochs |
subtract_evoked ([evoked]) |
Subtract an evoked response from each epoch |
time_as_index (times[, use_rounding]) |
Convert time to indices |
to_data_frame ([picks, index, scale_time, ...]) |
Export data in tabular structure as a pandas DataFrame. |
__init__
(raw, events, event_id=None, tmin=-0.2, tmax=0.5, 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', reject_by_annotation=True, verbose=None)¶add_channels
(add_list, copy=None, force_update_info=False)¶Append new channels to the instance.
Parameters: | add_list : list
copy : bool
force_update_info : bool
|
---|---|
Returns: | inst : instance of Raw, Epochs, or Evoked
|
add_eeg_average_proj
()¶Add an average EEG reference projector if one does not exist
add_proj
(projs, remove_existing=False, verbose=None)¶Add SSP projection vectors
Parameters: | projs : list
remove_existing : bool
verbose : bool, str, int, or None
|
---|---|
Returns: | self : instance of Raw | Epochs | Evoked
|
apply_baseline
(baseline, copy=None, verbose=None)¶Baseline correct epochs
Parameters: | baseline : tuple of length 2
copy : bool
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
|
Notes
Computes an average of all epochs in the instance, even if
they correspond to different conditions. To average by condition,
do epochs[condition].average()
for each condition separately.
ch_names
¶Channel names
copy
()¶Return copy of Epochs instance
crop
(tmin=None, tmax=None, copy=None)¶Crops a time interval from epochs object.
Parameters: | tmin : float | None
tmax : float | None
copy : bool
|
---|---|
Returns: | epochs : instance of Epochs
|
Notes
Unlike Python slices, MNE time intervals include both their end points; crop(tmin, tmax) returns the interval tmin <= t <= tmax.
decimate
(decim, copy=None, offset=0)¶Decimate the epochs
Parameters: | decim : int
copy : bool
offset : int
|
---|---|
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
(indices, reason='USER', verbose=None)¶Drop epochs based on indices or boolean mask
Note
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 mne.Epochs.drop_bad()
or
mne.Epochs.load_data()
methods.
Parameters: | indices : array of ints or bools
reason : str
verbose : bool, str, int, or None
|
---|---|
Returns: | epochs : instance of Epochs
|
drop_bad
(reject='existing', flat='existing', verbose=None)¶Drop bad epochs without retaining the epochs data.
Should be used before slicing operations.
Warning
This operation is slow since all epochs have to be read
from disk. To avoid reading epochs from disk multiple
times, use mne.Epochs.load_data()
.
Parameters: | reject : dict | str | None
flat : dict | str | None
verbose : bool, str, int, or None
|
---|---|
Returns: | epochs : instance of Epochs
|
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_bad_epochs
(*args, **kwargs)¶Warning
DEPRECATED: drop_bad_epochs method has been renamed drop_bad. drop_bad_epochs method will be removed in 0.13
Drop bad epochs without retaining the epochs data
drop_channels
(ch_names, copy=None)¶Drop some channels
Parameters: | ch_names : list
copy : bool
|
---|---|
Returns: | inst : instance of Raw, Epochs, or Evoked
|
See also
Notes
New in version 0.9.0.
drop_epochs
(*args, **kwargs)¶Warning
DEPRECATED: drop_epochs method has been renamed drop. drop_epochs method will be removed in 0.13
Drop epochs based on indices or boolean mask
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=None)¶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: | inst : instance of Raw, Epochs, or Evoked
|
Notes
New in version 0.9.0.
iter_evoked
()¶Iterate over epochs as a sequence of Evoked objects
The Evoked objects yielded will each contain a single epoch (i.e., no averaging is performed).
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)¶Iterate over epoch data.
Parameters: | return_event_id : bool
|
---|---|
Returns: | epoch : array of shape (n_channels, n_times)
event_id : int
|
pick_channels
(ch_names, copy=None)¶Pick some channels
Parameters: | ch_names : list
copy : bool
|
---|---|
Returns: | inst : instance of Raw, Epochs, or Evoked
|
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, bio=False, ecog=False, include=[], exclude='bads', selection=None, copy=None)¶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
bio : bool
ecog : bool
include : list of string
exclude : list of string | str
selection : list of string
copy : bool
|
---|---|
Returns: | inst : instance of Raw, Epochs, or Evoked
|
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_image
(picks=None, sigma=0.0, vmin=None, vmax=None, colorbar=True, order=None, show=True, units=None, scalings=None, cmap='RdBu_r', fig=None, overlay_times=None)¶Plot Event Related Potential / Fields image
Parameters: | picks : int | array-like of int | None
sigma : float
vmin : float
vmax : float
colorbar : bool
order : None | array of int | callable
show : bool
units : dict | None
scalings : dict | None
cmap : matplotlib colormap
fig : matplotlib figure | None
overlay_times : array-like, shape (n_epochs,) | None
|
---|---|
Returns: | figs : list of matplotlib figures
|
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, bandwidth=None, adaptive=False, low_bias=True, normalization='length', picks=None, ax=None, color='black', area_mode='std', area_alpha=0.33, dB=True, n_jobs=1, verbose=None, show=True)¶Plot the power spectral density across epochs
Parameters: | fmin : float
fmax : float
proj : bool
bandwidth : float
adaptive : bool
low_bias : bool
normalization : str
picks : array-like of int | None
ax : instance of matplotlib Axes | None
color : str | tuple
area_mode : str | None
area_alpha : float
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, bandwidth=None, adaptive=False, low_bias=True, normalization='length', ch_type=None, 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
bandwidth : float
adaptive : bool
low_bias : bool
normalization : str
ch_type : {None, ‘mag’, ‘grad’, ‘planar1’, ‘planar2’, ‘eeg’}
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
|
plot_sensors
(kind='topomap', ch_type=None, title=None, show_names=False, show=True)¶Plot sensors positions.
Parameters: | kind : str
ch_type : ‘mag’ | ‘grad’ | ‘eeg’ | ‘seeg’ | ‘ecog’ | None
title : str | None
show_names : bool
show : bool
|
---|---|
Returns: | fig : instance of matplotlib figure
|
See also
Notes
This function plots the sensor locations from the info structure using
matplotlib. For drawing the sensors using mayavi see
mne.viz.plot_trans()
.
New in version 0.12.0.
plot_topo_image
(layout=None, sigma=0.0, vmin=None, vmax=None, colorbar=True, order=None, cmap='RdBu_r', layout_scale=0.95, title=None, scalings=None, border='none', fig_facecolor='k', font_color='w', show=True)¶Plot Event Related Potential / Fields image on topographies
Parameters: | layout: instance of Layout :
sigma : float
vmin : float
vmax : float
colorbar : bool
order : None | array of int | callable
cmap : instance of matplotlib.pyplot.colormap
layout_scale: float :
title : str
scalings : dict | None
border : str
fig_facecolor : str | obj
font_color : str | obj
show : bool
|
---|---|
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=None, window='boxcar', n_jobs=1, copy=None, verbose=None)¶Resample preloaded data
Parameters: | sfreq : float
npad : int | str
window : string or tuple
n_jobs : int
copy : bool
verbose : bool, str, int, or None
|
---|---|
Returns: | epochs : instance of Epochs
|
See also
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, copy=False)¶Filter the data using Savitzky-Golay polynomial method
Parameters: | h_freq : float
copy : bool
|
---|---|
Returns: | inst : instance of Epochs or Evoked
|
See also
Notes
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, verbose=None)¶Set EEG sensor configuration
Parameters: | montage : instance of Montage or DigMontage
verbose : bool, str, int, or None
|
---|
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.
time_as_index
(times, use_rounding=False)¶Convert time to indices
Parameters: | times : list-like | float | int
use_rounding : boolean
|
---|---|
Returns: | index : ndarray
|
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
|