Epochs extracted from a Raw instance.
Raw
objectAn instance of Raw
.
array
of int
, shape (n_events, 3)The array of events. The first column contains the event time in
samples, with first_samp included. The third column contains the
event id.
If some events don’t match the events of interest as specified by event_id,
they will be marked as IGNORED
in the drop log.
int
| list
of int
| dict
| None
The id of the events to consider. If dict, the keys can later be used to access associated events. Example: dict(auditory=1, visual=3). If int, a dict will be created with the id as string. If a list, all events with the IDs specified in the list are used. If None, all events will be used and a dict is created with string integer names corresponding to the event id integers.
float
Start and end time of the epochs in seconds, relative to the time-locked
event. The closest or matching samples corresponding to the start and end
time are included. Defaults to -0.2
and 0.5
, respectively.
None
| tuple
of length 2The time interval to consider as “baseline” when applying baseline
correction. If None
, do not apply baseline correction.
If a tuple (a, b)
, the interval is between a
and b
(in seconds), including the endpoints.
If a
is None
, the beginning of the data is used; and if b
is None
, it is set to the end of the interval.
If (None, None)
, the entire time interval is used.
Note
The baseline (a, b)
includes both endpoints, i.e. all
timepoints t
such that a <= t <= b
.
Correction is applied to each epoch and channel individually in the following way:
Calculate the mean signal of the baseline period.
Subtract this mean from the entire epoch.
Defaults to (None, 0)
, i.e. beginning of the the data until
time point zero.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels. Note that channels in
info['bads']
will be included if their names or indices are
explicitly provided.
Load all epochs from disk when creating the object or wait before accessing each epoch (more memory efficient but can be slower).
dict
| None
Reject epochs based on maximum peak-to-peak signal amplitude (PTP), i.e. the absolute difference between the lowest and the highest signal value. In each individual epoch, the PTP is calculated for every channel. If the PTP of any one channel exceeds the rejection threshold, the respective epoch will be dropped.
The dictionary keys correspond to the different channel types; valid keys can be any channel type present in the object.
Example:
reject = dict(grad=4000e-13, # unit: T / m (gradiometers)
mag=4e-12, # unit: T (magnetometers)
eeg=40e-6, # unit: V (EEG channels)
eog=250e-6 # unit: V (EOG channels)
)
Note
Since rejection is based on a signal difference calculated for each channel separately, applying baseline correction does not affect the rejection procedure, as the difference will be preserved.
Note
To constrain the time period used for estimation of signal
quality, pass the reject_tmin
and reject_tmax
parameters.
If reject
is None
(default), no rejection is performed.
dict
| None
Reject epochs based on minimum peak-to-peak signal amplitude (PTP).
Valid keys can be any channel type present in the object. The
values are floats that set the minimum acceptable PTP. If the PTP
is smaller than this threshold, the epoch will be dropped. If None
then no rejection is performed based on flatness of the signal.
Note
To constrain the time period used for estimation of signal
quality, pass the reject_tmin
and reject_tmax
parameters.
Apply SSP projection vectors. If proj is ‘delayed’ and reject is not None the single epochs will be projected before the rejection decision, but used in unprojected state if they are kept. This way deciding which projection vectors are good can be postponed to the evoked stage without resulting in lower epoch counts and without producing results different from early SSP application given comparable parameters. Note that in this case baselining, detrending and temporal decimation will be postponed. If proj is False no projections will be applied which is the recommended value if SSPs are not used for cleaning the data.
int
Factor by which to subsample the data.
Warning
Low-pass filtering is not performed, this simply selects
every Nth sample (where N is the value passed to
decim
), i.e., it compresses the signal (see Notes).
If the data are not properly filtered, aliasing artifacts
may occur.
float
| None
Start and end of the time window used to reject epochs based on
peak-to-peak (PTP) amplitudes as specified via reject
and flat
.
The default None
corresponds to the first and last time points of the
epochs, respectively.
Note
This parameter controls the time period used in conjunction with
both, reject
and flat
.
int
| None
If 0 or 1, the data channels (MEG and EEG) will be detrended when loaded. 0 is a constant (DC) detrend, 1 is a linear detrend. None is no detrending. Note that detrending is performed before baseline correction. If no DC offset is preferred (zeroth order detrending), either turn off baseline correction, as this may introduce a DC shift, or set baseline correction to use the entire time interval (will yield equivalent results but be slower).
What to do if one or several event ids are not found in the recording.
Valid keys are ‘raise’ | ‘warn’ | ‘ignore’
Default is 'raise'
. If 'warn'
, it will proceed but
warn; if 'ignore'
, it will proceed silently.
Note
If none of the event ids are found in the data, an error will be automatically generated irrespective of this parameter.
Whether to reject based on annotations. If True
(default), epochs
overlapping with segments whose description begins with 'bad'
are
rejected. If False
, no rejection based on annotations is performed.
pandas.DataFrame
| None
A pandas.DataFrame
specifying metadata about each epoch.
If given, len(metadata)
must equal len(events)
. The DataFrame
may only contain values of type (str | int | float | bool).
If metadata is given, then pandas-style queries may be used to select
subsets of data, see mne.Epochs.__getitem__()
.
When a subset of the epochs is created in this (or any other
supported) manner, the metadata object is subsetted accordingly, and
the row indices will be modified to match epochs.selection
.
New in version 0.16.
str
How to handle duplicates in events[:, 0]
. Can be 'error'
(default), to raise an error, ‘drop’ to only retain the row occurring
first in the events, or 'merge'
to combine the coinciding
events (=duplicates) into a new event (see Notes for details).
New in version 0.19.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
When accessing data, Epochs are detrended, baseline-corrected, and decimated, then projectors are (optionally) applied.
For indexing and slicing using epochs[...]
, see
mne.Epochs.__getitem__()
.
All methods for iteration over objects (using mne.Epochs.__iter__()
,
mne.Epochs.iter_evoked()
or mne.Epochs.next()
) use the same
internal state.
If event_repeated
is set to 'merge'
, the coinciding events
(duplicates) will be merged into a single event_id and assigned a new
id_number as:
event_id['{event_id_1}/{event_id_2}/...'] = new_id_number
For example with the event_id {'aud': 1, 'vis': 2}
and the events
[[0, 0, 1], [0, 0, 2]]
, the “merge” behavior will update both event_id
and events to be: {'aud/vis': 3}
and [[0, 0, 3]]
respectively.
There is limited support for Annotations
in the
Epochs
class. Currently annotations that are present in the
Raw
object will be preserved in the resulting
Epochs
object, but:
It is not yet possible to add annotations to the Epochs object programmatically (via code) or interactively (through the plot window)
Concatenating Epochs
objects
that contain annotations is not supported, and any annotations will
be dropped when concatenating.
Annotations will be lost on save.
mne.Info
The mne.Info
object with information about the sensors and methods of measurement.
dict
Names of conditions corresponding to event_ids.
ch_names
list
of str
Channel names.
array
List of indices of selected events (not dropped or ignored etc.). For example, if the original event array had 4 events and the second event has been dropped, this attribute would be np.array([0, 2, 3]).
Indicates whether epochs are in memory.
tuple
of tuple
A tuple of the same length as the event array used to initialize the Epochs object. If the i-th original event is still part of the selection, drop_log[i] will be an empty tuple; otherwise it will be a tuple of the reasons the event is not longer in the selection, e.g.:
If it isn’t part of the current subset defined by the user
If epoch didn’t contain enough data names of channels that exceeded the amplitude threshold
For user-defined reasons (see drop()
).
filename
str
The filename.
times
ndarray
Time vector in seconds.
Methods
|
Check channel type membership. |
|
Return an Epochs object with a copied subset of epochs. |
|
Facilitate iteration over epochs. |
|
Return the number of epochs. |
|
Add raw annotations into the Epochs metadata data frame. |
|
Append new channels to the instance. |
|
Add SSP projection vectors. |
|
Add reference channels to data that consists of all zeros. |
|
Anonymize measurement information in place. |
|
Baseline correct epochs. |
|
Apply a function to a subset of channels. |
|
Compute analytic signal or envelope for a subset of channels. |
|
Apply the signal space projection (SSP) operators to the data. |
|
Compute virtual epochs using interpolated fields. |
|
Compute an average over epochs. |
|
Return copy of Epochs instance. |
|
Crop a time interval from the epochs. |
|
Decimate the time-series data. |
|
Remove SSP projection vector. |
|
Drop epochs based on indices or boolean mask. |
|
Drop bad epochs without retaining the epochs data. |
|
Drop channel(s). |
|
Compute the channel stats based on a drop_log from Epochs. |
|
Equalize the number of trials in each condition. |
|
Export Epochs to external formats. |
|
Filter a subset of channels. |
Get a list of annotations that occur during each epoch. |
|
|
Get a list of channel type for each channel. |
|
Get all epochs as a 3D array. |
Get a DigMontage from instance. |
|
|
Interpolate bad MEG and EEG channels. |
|
Iterate over epochs as a sequence of Evoked objects. |
Load the data if not already preloaded. |
|
|
Iterate over epoch data. |
|
Pick a subset of channels. |
|
Pick some channels. |
|
Pick some channels by type and names. |
|
Visualize epochs. |
|
Show the channel stats based on a drop_log from Epochs. |
|
Plot Event Related Potential / Fields image. |
|
Plot SSP vector. |
|
Plot the power spectral density across channels. |
|
Plot the topomap of the power spectral density across epochs. |
|
Plot sensor positions. |
|
Plot Event Related Potential / Fields image on topographies. |
|
Rename channels. |
|
Reorder channels. |
|
Resample data. |
Reset the drop_log and selection entries. |
|
|
Save epochs in a fif file. |
|
Filter the data using Savitzky-Golay polynomial method. |
|
Setter for Epoch annotations from Raw. |
|
Define the sensor type of channels. |
|
Specify which reference to use for EEG data. |
|
Set the measurement start date. |
|
Set EEG/sEEG/ECoG/DBS/fNIRS channel positions and digitization points. |
|
Shift time scale in epoched or evoked data. |
|
Compute standard error over epochs. |
|
Subtract an evoked response from each epoch. |
|
Convert time to indices. |
|
Export data in tabular structure as a pandas DataFrame. |
Check channel type membership.
str
Channel type to check for. Can be e.g. ‘meg’, ‘eeg’, ‘stim’, etc.
Whether or not the instance contains the given channel type.
Examples
Channel type membership can be tested as:
>>> 'meg' in inst
True
>>> 'seeg' in inst
False
Return an Epochs object with a copied subset of epochs.
slice
, array-like, str
, or list
See below for use cases.
Epochs
See below for use cases.
Notes
Epochs can be accessed as epochs[...]
in several ways:
Integer or slice: epochs[idx]
will return an Epochs
object with a subset of epochs chosen by index (supports single
index and Python-style slicing).
String: epochs['name']
will return an Epochs
object
comprising only the epochs labeled 'name'
(i.e., epochs created
around events with the label 'name'
).
If there are no epochs labeled 'name'
but there are epochs
labeled with /-separated tags (e.g. 'name/left'
,
'name/right'
), then epochs['name']
will select the epochs
with labels that contain that tag (e.g., epochs['left']
selects
epochs labeled 'audio/left'
and 'visual/left'
, but not
'audio_left'
).
If multiple tags are provided as a single string (e.g.,
epochs['name_1/name_2']
), this selects epochs containing all
provided tags. For example, epochs['audio/left']
selects
'audio/left'
and 'audio/quiet/left'
, but not
'audio/right'
. Note that tag-based selection is insensitive to
order: tags like 'audio/left'
and 'left/audio'
will be
treated the same way when selecting via tag.
List of strings: epochs[['name_1', 'name_2', ... ]]
will
return an Epochs
object comprising epochs that match any of
the provided names (i.e., the list of names is treated as an
inclusive-or condition). If none of the provided names match any
epoch labels, a KeyError
will be raised.
If epoch labels are /-separated tags, then providing multiple tags
as separate list entries will likewise act as an inclusive-or
filter. For example, epochs[['audio', 'left']]
would select
'audio/left'
, 'audio/right'
, and 'visual/left'
, but not
'visual/right'
.
Pandas query: epochs['pandas query']
will return an
Epochs
object with a subset of epochs (and matching
metadata) selected by the query called with
self.metadata.eval
, e.g.:
epochs["col_a > 2 and col_b == 'foo'"]
would return all epochs whose associated col_a
metadata was
greater than two, and whose col_b
metadata was the string ‘foo’.
Query-based indexing only works if Pandas is installed and
self.metadata
is a pandas.DataFrame
.
New in version 0.16.
Facilitate iteration over epochs.
This method resets the object iteration state to the first epoch.
Notes
This enables the use of this Python pattern:
>>> for epoch in epochs:
>>> print(epoch)
Where epoch
is given by successive outputs of
mne.Epochs.next()
.
Return the number of epochs.
int
The number of remaining epochs.
Notes
This function only works if bad epochs have been dropped.
Examples
This can be used as:
>>> epochs.drop_bad()
>>> len(epochs)
43
>>> len(epochs.events)
43
Add raw annotations into the Epochs metadata data frame.
Adds three columns to the metadata
consisting of a list
in each row:
- annot_onset
: the onset of each Annotation within
the Epoch relative to the start time of the Epoch (in seconds).
- annot_duration
: the duration of each Annotation
within the Epoch in seconds.
- annot_description
: the free-form text description of each
Annotation.
Whether to overwrite existing columns in metadata or not. Default is False.
Epochs
The modified instance (instance is also modified inplace).
Notes
New in version 1.0.
Append new channels to the instance.
list
A list of objects to append to self. Must contain all the same type as the current object.
If True, force the info for objects to be appended to match the
values in self
. This should generally only be used when adding
stim channels for which important metadata won’t be overwritten.
New in version 0.12.
See also
Notes
If self
is a Raw instance that has been preloaded into a
numpy.memmap
instance, the memmap will be resized.
Add SSP projection vectors.
list
List with projection vectors.
Remove the projection vectors currently in the file.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Examples using add_proj
:
The Epochs data structure: discontinuous data
Add reference channels to data that consists of all zeros.
Adds reference channels to data that were not included during recording. This is useful when you need to re-reference your data to different channels. These added channels will consist of all zeros.
Anonymize measurement information in place.
int
| None
Number of days to subtract from all dates.
If None
(default), the acquisition date, info['meas_date']
,
will be set to January 1ˢᵗ, 2000
. This parameter is ignored if
info['meas_date']
is None
(i.e., no acquisition date has been set).
If True
, his_id
of subject_info
will not be overwritten.
Defaults to False
.
Warning
This could mean that info
is not fully
anonymized. Use with caution.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
Removes potentially identifying information if it exists in info
.
Specifically for each of the following we use:
A default value, or as specified by daysback
.
Default values, except for ‘birthday’ which is adjusted to maintain the subject age.
Default strings.
None
.
Zeros.
Dates use the meas_date
logic, and experimenter a default string.
Dates use the meas_date
logic, meta info uses defaults.
If info['meas_date']
is None
, it will remain None
during processing
the above fields.
Operates in place.
New in version 0.13.0.
Baseline correct epochs.
None
| tuple
of length 2The time interval to consider as “baseline” when applying baseline
correction. If None
, do not apply baseline correction.
If a tuple (a, b)
, the interval is between a
and b
(in seconds), including the endpoints.
If a
is None
, the beginning of the data is used; and if b
is None
, it is set to the end of the interval.
If (None, None)
, the entire time interval is used.
Note
The baseline (a, b)
includes both endpoints, i.e. all
timepoints t
such that a <= t <= b
.
Correction is applied to each epoch and channel individually in the following way:
Calculate the mean signal of the baseline period.
Subtract this mean from the entire epoch.
Defaults to (None, 0)
, i.e. beginning of the the data until
time point zero.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Epochs
The baseline-corrected Epochs object.
Notes
Baseline correction can be done multiple times, but can never be reverted once the data has been loaded.
New in version 0.10.0.
Examples using apply_baseline
:
Repairing artifacts with regression
Apply a function to a subset of channels.
The function fun
is applied to the channels defined in picks
.
The epochs object’s data is modified in-place. If the function returns a different
data type (e.g. numpy.complex128
) it must be specified
using the dtype
parameter, which causes the data type of all the data
to change (even if the function is only applied to channels in picks
). The object has to have the data loaded e.g. with preload=True
or self.load_data()
.
Note
If n_jobs
> 1, more memory is required as
len(picks) * n_times
additional time points need to
be temporarily stored in memory.
Note
If the data type changes (dtype != None
), more memory is
required since the original and the converted data needs
to be stored in memory.
callable()
A function to be applied to the channels. The first argument of
fun has to be a timeseries (numpy.ndarray
). The function must
operate on an array of shape (n_times,)
if channel_wise=True
and (len(picks), n_times)
otherwise.
The function must return an ndarray
shaped like its input.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all data channels (excluding reference
MEG channels). Note that channels in info['bads']
will be included if
their names or indices are explicitly provided.
numpy.dtype
Data type to use after applying the function. If None (default) the data type is not modified.
int
| None
The number of jobs to run in parallel. If -1
, it is set
to the number of CPU cores. Requires the joblib
package.
None
(default) is a marker for ‘unset’ that will be interpreted
as n_jobs=1
(sequential execution) unless the call is performed under
a joblib.parallel_backend()
context manager that sets another
value for n_jobs
.
Whether to apply the function to each channel in each epoch individually. If False
,
the function will be applied to all epochs and channels at once. Default True
.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
dict
Additional keyword arguments to pass to fun
.
Epochs
The epochs object with transformed data.
Compute analytic signal or envelope for a subset of channels.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all data channels (excluding reference
MEG channels). Note that channels in info['bads']
will be included if
their names or indices are explicitly provided.
Compute the envelope signal of each channel. Default False. See Notes.
int
| None
The number of jobs to run in parallel. If -1
, it is set
to the number of CPU cores. Requires the joblib
package.
None
(default) is a marker for ‘unset’ that will be interpreted
as n_jobs=1
(sequential execution) unless the call is performed under
a joblib.parallel_backend()
context manager that sets another
value for n_jobs
.
int
| None
| str
Points to use in the FFT for Hilbert transformation. The signal will be padded with zeros before computing Hilbert, then cut back to original length. If None, n == self.n_times. If ‘auto’, the next highest fast FFT length will be use.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
Parameters
If envelope=False
, the analytic signal for the channels defined in
picks
is computed and the data of the Raw object is converted to
a complex representation (the analytic signal is complex valued).
If envelope=True
, the absolute value of the analytic signal for the
channels defined in picks
is computed, resulting in the envelope
signal.
If envelope=False, more memory is required since the original raw data
as well as the analytic signal have temporarily to be stored in memory.
If n_jobs > 1, more memory is required as len(picks) * n_times
additional time points need to be temporaily stored in memory.
Also note that the n_fft
parameter will allow you to pad the signal
with zeros before performing the Hilbert transform. This padding
is cut off, but it may result in a slightly different result
(particularly around the edges). Use at your own risk.
Analytic signal
The analytic signal “x_a(t)” of “x(t)” is:
x_a = F^{-1}(F(x) 2U) = x + i y
where “F” is the Fourier transform, “U” the unit step function, and “y” the Hilbert transform of “x”. One usage of the analytic signal is the computation of the envelope signal, which is given by “e(t) = abs(x_a(t))”. Due to the linearity of Hilbert transform and the MNE inverse solution, the enevlope in source space can be obtained by computing the analytic signal in sensor space, applying the MNE inverse, and computing the envelope in source space.
Apply the signal space projection (SSP) operators to the data.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
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
Examples using apply_proj
:
Compute virtual epochs using interpolated fields.
Warning
Using virtual epochs to compute inverse can yield
unexpected results. The virtual channels have '_v'
appended
at the end of the names to emphasize that the data contained in
them are interpolated.
mne.EpochsArray
The transformed epochs object containing only virtual channels.
Notes
This method returns a copy and does not modify the data it operates on. It also returns an EpochsArray instance.
New in version 0.20.0.
Compute an average over epochs.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all data channels. Note that channels
in info['bads']
will be included if their names or indices are
explicitly provided.
str
| callable()
How to combine the data. If “mean”/”median”, the mean/median are returned. Otherwise, must be a callable which, when passed an array of shape (n_epochs, n_channels, n_time) returns an array of shape (n_channels, n_time). Note that due to file type limitations, the kind for all these will be “average”.
When False
(the default) all epochs are processed together and a single
Evoked
object is returned. When True
, epochs are first
grouped by event type (as specified using the event_id
parameter) and a
list is returned containing a separate Evoked
object for each
event type. The .comment
attribute is set to the label of the event
type.
New in version 0.24.0.
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.
When picks is None and epochs contain only ICA channels, no channels are selected, resulting in an error. This is because ICA channels are not considered data channels (they are of misc type) and only data channels are selected when picks is None.
The method
parameter allows e.g. robust averaging.
For example, one could do:
>>> from scipy.stats import trim_mean
>>> trim = lambda x: trim_mean(x, 0.1, axis=0)
>>> epochs.average(method=trim)
This would compute the trimmed mean.
Examples using average
:
Overview of MEG/EEG analysis with MNE-Python
Getting started with mne.Report
Overview of artifact detection
Rejecting bad data spans and breaks
Repairing artifacts with regression
The Evoked data structure: evoked/averaged data
EEG analysis - Event-Related Potentials (ERPs)
4D Neuroimaging/BTi phantom dataset tutorial
Non-parametric 1 sample cluster statistic on single trial power
Non-parametric between conditions cluster statistic on single trial power
Permutation t-test on source data with spatio-temporal clustering
Corrupt known signal with point spread
Getting averaging info from .fif files
Generate simulated source data
Maxwell filter data with movement compensation
Whitening evoked data with a noise covariance
Compute MNE-dSPM inverse solution on single epochs
Compute source power estimate by projecting the covariance with MNE
Brainstorm raw (median nerve) dataset
Channel names.
The current gradient compensation grade.
Return copy of Epochs instance.
Epochs
A copy of the object.
Examples using copy
:
The Epochs data structure: discontinuous data
Regression-based baseline correction
Compute power and phase lock in label of the source space
Motor imagery decoding from EEG data using the Common Spatial Pattern (CSP)
Decoding in time-frequency space using Common Spatial Patterns (CSP)
Linear classifier on sensor data with plot patterns and filters
Crop a time interval from the epochs.
float
| None
Start time of selection in seconds.
float
| None
End time of selection in seconds.
If True (default), include tmax. If False, exclude tmax (similar to how Python indexing typically works).
New in version 0.19.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Epochs
The cropped epochs object, modified in-place.
Notes
Unlike Python slices, MNE time intervals by default include both
their end points; crop(tmin, tmax)
returns the interval
tmin <= t <= tmax
. Pass include_tmax=False
to specify the half-open
interval tmin <= t < tmax
instead.
Examples using crop
:
The Epochs data structure: discontinuous data
Decimate the time-series data.
int
Factor by which to subsample the data.
Warning
Low-pass filtering is not performed, this simply selects
every Nth sample (where N is the value passed to
decim
), i.e., it compresses the signal (see Notes).
If the data are not properly filtered, aliasing artifacts
may occur.
int
Apply an offset to where the decimation starts relative to the sample corresponding to t=0. The offset is in samples at the current sampling rate.
New in version 0.12.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
The decimated object.
See also
Notes
For historical reasons, decim
/ “decimation” refers to simply subselecting
samples from a given signal. This contrasts with the broader signal processing
literature, where decimation is defined as (quoting
[1], p. 172; which cites
[2]):
“… a general system for downsampling by a factor of M is the one shown in Figure 4.23. Such a system is called a decimator, and downsampling by lowpass filtering followed by compression [i.e, subselecting samples] has been termed decimation (Crochiere and Rabiner, 1983).”
Hence “decimation” in MNE is what is considered “compression” in the signal processing community.
Decimation can be done multiple times. For example,
inst.decimate(2).decimate(2)
will be the same as
inst.decimate(4)
.
If decim
is 1, this method does not copy the underlying data.
New in version 0.10.0.
References
Examples using decimate
:
Remove SSP projection vector.
Note
The projection vector can only be removed if it is inactive (has not been applied to the data).
Examples using del_proj
:
The Epochs data structure: discontinuous data
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.
array
of int
or boolSet epochs to remove by specifying indices to remove or a boolean mask to apply (where True values get removed). Events are correspondingly modified.
str
Reason for dropping the epochs (‘ECG’, ‘timeout’, ‘blink’ etc). Default: ‘USER’.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Epochs
The epochs with indices dropped. Operates in-place.
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()
.
Note
To constrain the time period used for estimation of signal
quality, set epochs.reject_tmin
and
epochs.reject_tmax
, respectively.
dict
| str
| None
Reject epochs based on maximum peak-to-peak signal amplitude (PTP), i.e. the absolute difference between the lowest and the highest signal value. In each individual epoch, the PTP is calculated for every channel. If the PTP of any one channel exceeds the rejection threshold, the respective epoch will be dropped.
The dictionary keys correspond to the different channel types; valid keys can be any channel type present in the object.
Example:
reject = dict(grad=4000e-13, # unit: T / m (gradiometers)
mag=4e-12, # unit: T (magnetometers)
eeg=40e-6, # unit: V (EEG channels)
eog=250e-6 # unit: V (EOG channels)
)
Note
Since rejection is based on a signal difference calculated for each channel separately, applying baseline correction does not affect the rejection procedure, as the difference will be preserved.
If reject
is None
, no rejection is performed. If 'existing'
(default), then the rejection parameters set at instantiation are used.
dict
| str
| None
Reject epochs based on minimum peak-to-peak signal amplitude (PTP).
Valid keys can be any channel type present in the object. The
values are floats that set the minimum acceptable PTP. If the PTP
is smaller than this threshold, the epoch will be dropped. If None
then no rejection is performed based on flatness of the signal.
If 'existing'
, then the flat parameters set during epoch creation are
used.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Epochs
The epochs with bad epochs dropped. Operates in-place.
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.
Examples using drop_bad
:
Rejecting bad data spans and breaks
EEG analysis - Event-Related Potentials (ERPs)
Decoding in time-frequency space using Common Spatial Patterns (CSP)
Compute effect-matched-spatial filtering (EMS)
Drop channel(s).
See also
Notes
New in version 0.9.0.
Examples using drop_channels
:
The Epochs data structure: discontinuous data
Spatiotemporal permutation F-test on full sensor data
Compute the channel stats based on a drop_log from Epochs.
list
The drop reasons to ignore.
float
Total percentage of epochs dropped.
See also
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
within a Epochs
instance. For example, if one event type
occurred at time points [1, 2, 3, 4, 120, 121]
and the another one
at [3.5, 4.5, 120.5, 121.5]
, this method would remove the events at
times [1, 2]
for the first event type – and not the events at times
[120, 121]
.
None
| list
| dict
The event types to equalize.
If None
(default), equalize the counts of all event types
present in the Epochs
instance.
If a list, each element can either be a string (event name) or a list of strings. In the case where one of the entries is a list of strings, event types in that list will be grouped together before equalizing trial counts across conditions.
If a dictionary, the keys are considered as the event names whose
counts to equalize, i.e., passing dict(A=1, B=2)
will have the
same effect as passing ['A', 'B']
. This is useful if you intend
to pass an event_id
dictionary that was used when creating
Epochs
.
In the case where partial matching is used (using /
in
the event names), the event types will be matched according to the
provided tags, that is, processing works as if the event_ids
matched by the provided tags had been supplied instead.
The event_ids
must identify non-overlapping subsets of the
epochs.
str
If 'truncate'
, events will be truncated from the end of each
type of events. If 'mintime'
, timing differences between each
event type will be minimized.
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 combined.
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 equally. E.g., it is possible to end up
with 70 'Nonspatial'
epochs, 69 'Left'
and 1 'Right'
.
Changed in version 0.23: Default to equalizing all events in the passed instance if no event names were specified explicitly.
Examples using equalize_event_counts
:
The Evoked data structure: evoked/averaged data
Mass-univariate twoway repeated measures ANOVA on single trial power
Spatiotemporal permutation F-test on full sensor data
Repeated measures ANOVA on source data with spatio-temporal clustering
Compute effect-matched-spatial filtering (EMS)
Export Epochs to external formats.
EEGLAB (.set
, uses eeglabio
)
Warning
Since we are exporting to external formats, there’s no guarantee that all the info will be preserved in the external format. See Notes for details.
str
Name of the output file.
Format of the export. Defaults to 'auto'
, which will infer the format
from the filename extension. See supported formats above for more
information.
If True (default False), overwrite the destination file if it exists.
New in version 0.24.1.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
New in version 0.24.
Export to external format may not preserve all the information from the
instance. To save in native MNE format (.fif
) without information loss,
use mne.Epochs.save()
instead.
Export does not apply projector(s). Unapplied projector(s) will be lost.
Consider applying projector(s) before exporting with
mne.Epochs.apply_proj()
.
For EEGLAB exports, channel locations are expanded to full EEGLAB format.
For more details see eeglabio.utils.cart_to_eeglab()
.
The filename.
Filter a subset of channels.
float
| None
For FIR filters, the lower pass-band edge; for IIR filters, the lower cutoff frequency. If None the data are only low-passed.
float
| None
For FIR filters, the upper pass-band edge; for IIR filters, the upper cutoff frequency. If None the data are only high-passed.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all data channels. Note that channels
in info['bads']
will be included if their names or indices are
explicitly provided.
str
| int
Length of the FIR filter to use (if applicable):
‘auto’ (default): The filter length is chosen based on the size of the transition regions (6.6 times the reciprocal of the shortest transition band for fir_window=’hamming’ and fir_design=”firwin2”, and half that for “firwin”).
str: A human-readable time in
units of “s” or “ms” (e.g., “10s” or “5500ms”) will be
converted to that number of samples if phase="zero"
, or
the shortest power-of-two length at least that duration for
phase="zero-double"
.
int: Specified length in samples. For fir_design=”firwin”, this should not be used.
float
| str
Width of the transition band at the low cut-off frequency in Hz
(high pass or cutoff 1 in bandpass). Can be “auto”
(default) to use a multiple of l_freq
:
min(max(l_freq * 0.25, 2), l_freq)
Only used for method='fir'
.
float
| str
Width of the transition band at the high cut-off frequency in Hz
(low pass or cutoff 2 in bandpass). Can be “auto”
(default in 0.14) to use a multiple of h_freq
:
min(max(h_freq * 0.25, 2.), info['sfreq'] / 2. - h_freq)
Only used for method='fir'
.
int
| str
Number of jobs to run in parallel. Can be ‘cuda’ if cupy
is installed properly and method=’fir’.
str
‘fir’ will use overlap-add FIR filtering, ‘iir’ will use IIR forward-backward filtering (via filtfilt).
dict
| None
Dictionary of parameters to use for IIR filtering.
If iir_params is None and method=”iir”, 4th order Butterworth will be used.
For more information, see mne.filter.construct_iir_filter()
.
str
Phase of the filter, only used if method='fir'
.
Symmetric linear-phase FIR filters are constructed, and if phase='zero'
(default), the delay of this filter is compensated for, making it
non-causal. If phase='zero-double'
,
then this filter is applied twice, once forward, and once backward
(also making it non-causal). If 'minimum'
, then a minimum-phase filter
will be constricted and applied, which is causal but has weaker stop-band
suppression.
New in version 0.13.
str
The window to use in FIR design, can be “hamming” (default), “hann” (default in 0.13), or “blackman”.
New in version 0.15.
str
Can be “firwin” (default) to use scipy.signal.firwin()
,
or “firwin2” to use scipy.signal.firwin2()
. “firwin” uses
a time-domain design technique that generally gives improved
attenuation using fewer samples than “firwin2”.
New in version 0.15.
str
| list
of str
If a string (or list of str), any annotation segment that begins
with the given string will not be included in filtering, and
segments on either side of the given excluded annotated segment
will be filtered separately (i.e., as independent signals).
The default (('edge', 'bad_acq_skip')
will separately filter
any segments that were concatenated by mne.concatenate_raws()
or mne.io.Raw.append()
, or separated during acquisition.
To disable, provide an empty list. Only used if inst
is raw.
New in version 0.16..
str
The type of padding to use. Supports all numpy.pad()
mode
options. Can also be "reflect_limited"
, which pads with a
reflected version of each vector mirrored on the first and last values
of the vector, followed by zeros.
Only used for method='fir'
.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
Applies a zero-phase low-pass, high-pass, band-pass, or band-stop
filter to the channels selected by picks
.
The data are modified inplace.
The object has to have the data loaded e.g. with preload=True
or self.load_data()
.
l_freq
and h_freq
are the frequencies below which and above
which, respectively, to filter out of the data. Thus the uses are:
l_freq < h_freq
: band-pass filter
l_freq > h_freq
: band-stop filter
l_freq is not None and h_freq is None
: high-pass filter
l_freq is None and h_freq is not None
: low-pass filter
self.info['lowpass']
and self.info['highpass']
are only
updated with picks=None.
Note
If n_jobs > 1, more memory is required as
len(picks) * n_times
additional time points need to
be temporaily stored in memory.
For more information, see the tutorials
Background information on filtering and Filtering and resampling data and
mne.filter.create_filter()
.
New in version 0.15.
Examples using filter
:
The Epochs data structure: discontinuous data
Get a list of annotations that occur during each epoch.
list
A list of lists (with length equal to number of epochs) where each
inner list contains any annotations that overlap the corresponding
epoch. Annotations are stored as a tuple
of onset,
duration, description (not as a Annotations
object),
where the onset is now relative to time=0 of the epoch, rather than
time=0 of the original continuous (raw) data.
Get a list of channel type for each channel.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels. Note that channels in
info['bads']
will be included if their names or indices are
explicitly provided.
Whether to return only unique channel types. Default is False
.
Whether to ignore non-data channels. Default is False
.
list
The channel types.
Examples using get_channel_types
:
The Epochs data structure: discontinuous data
Get all epochs as a 3D array.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels. Note that channels in
info['bads']
will be included if their names or indices are
explicitly provided.
slice
| array-like | str
| list
| None
The items to get. See mne.Epochs.__getitem__()
for
a description of valid options. This can be substantially faster
for obtaining an ndarray than __getitem__()
for repeated access on large Epochs objects.
None (default) is an alias for slice(None)
.
New in version 0.20.
str
| dict
| None
Specify the unit(s) that the data should be returned in. If
None
(default), the data is returned in the
channel-type-specific default units, which are SI units (see
Internal representation (units) and data channels). If a string, must be a
sub-multiple of SI units that will be used to scale the data from
all channels of the type associated with that unit. This only works
if the data contains one channel type that has a unit (unitless
channel types are left unchanged). For example if there are only
EEG and STIM channels, units='uV'
will scale EEG channels to
micro-Volts while STIM channels will be unchanged. Finally, if a
dictionary is provided, keys must be channel types, and values must
be units to scale the data of that channel type to. For example
dict(grad='fT/cm', mag='fT')
will scale the corresponding types
accordingly, but all other channel types will remain in their
channel-type-specific default unit.
New in version 0.24.
int
| float
| None
Start time of data to get in seconds.
New in version 0.24.0.
int
| float
| None
End time of data to get in seconds.
New in version 0.24.0.
array
of shape (n_epochs, n_channels, n_times)A view on epochs data.
Examples using get_data
:
Background on projectors and projections
The Epochs data structure: discontinuous data
Divide continuous data into equally-spaced epochs
The Evoked data structure: evoked/averaged data
Permutation F-test on sensor data with 1D cluster level
FDR correction on T-test on sensor data
Permutation T-test on sensor data
Motor imagery decoding from EEG data using the Common Spatial Pattern (CSP)
Decoding in time-frequency space using Common Spatial Patterns (CSP)
Continuous Target Decoding with SPoC
Analysis of evoked response using ICA and PCA reduction techniques
Compute effect-matched-spatial filtering (EMS)
Linear classifier on sensor data with plot patterns and filters
Compute Spectro-Spatial Decomposition (SSD) spatial filters
Get a DigMontage from instance.
None
| str
| DigMontage
A montage containing channel positions. If a string or
DigMontage
is
specified, the existing channel information will be updated with the
channel positions from the montage. Valid strings are the names of the
built-in montages that ship with MNE-Python; you can list those via
mne.channels.get_builtin_montages()
.
If None
(default), the channel positions will be removed from the
Info
.
Examples using get_montage
:
Interpolate bad MEG and EEG channels.
Operates in place.
If True, remove the bads from info.
str
Either 'accurate'
or 'fast'
, determines the quality of the
Legendre polynomial expansion used for interpolation of channels
using the minimum-norm method.
str
Origin of the sphere in the head coordinate frame and in meters.
Can be 'auto'
(default), which means a head-digitization-based
origin fit.
New in version 0.17.
dict
Method to use for each channel type. Currently only the key “eeg” has multiple options:
"spline"
(default)Use spherical spline interpolation.
"MNE"
Use minimum-norm projection to a sphere and back. This is the method used for MEG channels.
The value for “meg” is “MNE”, and the value for “fnirs” is “nearest”. The default (None) is thus an alias for:
method=dict(meg="MNE", eeg="spline", fnirs="nearest")
New in version 0.21.
list
| tuple
The channels to exclude from interpolation. If excluded a bad channel will stay in bads.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
New in version 0.9.0.
Examples using interpolate_bads
:
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).
This method resets the object iteration state to the first epoch.
If False copies of data and measurement info will be omitted to save time.
Examples using iter_evoked
:
EEG analysis - Event-Related Potentials (ERPs)
Load the data if not already preloaded.
Epochs
The epochs object.
Notes
This function operates in-place.
New in version 0.10.0.
Examples using load_data
:
Rejecting bad data spans and breaks
Divide continuous data into equally-spaced epochs
Get the metadata.
Pick a subset of channels.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels. Note that channels in
info['bads']
will be included if their names or indices are
explicitly provided.
list
| str
Set of channels to exclude, only used when picking based on types (e.g., exclude=”bads” when picks=”meg”).
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
New in version 0.24.0.
Examples using pick
:
The Epochs data structure: discontinuous data
Pick some channels.
list
The list of channels to select.
If True (default False), ensure that the order of the channels in
the modified instance matches the order of ch_names
.
New in version 0.20.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
New in version 1.1.
See also
Notes
The channel names given are assumed to be a set, i.e. the order
does not matter. The original order of the channels is preserved.
You can use reorder_channels
to set channel order if necessary.
New in version 0.9.0.
Examples using pick_channels
:
The Epochs data structure: discontinuous data
Non-parametric 1 sample cluster statistic on single trial power
Non-parametric between conditions cluster statistic on single trial power
Mass-univariate twoway repeated measures ANOVA on single trial power
Pick some channels by type and names.
str
If True include MEG channels. If string it can be ‘mag’, ‘grad’, ‘planar1’ or ‘planar2’ to select only magnetometers, all gradiometers, or a specific type of gradiometer.
If True include EEG channels.
If True include stimulus channels.
If True include EOG channels.
If True include ECG channels.
If True include EMG channels.
str
If True include CTF / 4D reference channels. If ‘auto’, reference
channels are included if compensations are present and meg
is
not False. Can also be the string options for the meg
parameter.
If True include miscellaneous analog channels.
If True
include respiratory channels.
If True include continuous HPI coil channels.
Flux excitation channel used to be a stimulus channel.
Internal Active Shielding data (maybe on Triux only).
System status channel information (on Triux systems only).
Stereotactic EEG channels.
Dipole time course channels.
Dipole goodness of fit channels.
Bio channels.
Electrocorticography channels.
str
Functional near-infrared spectroscopy channels. If True include all fNIRS channels. If False (default) include none. If string it can be ‘hbo’ (to include channels measuring oxyhemoglobin) or ‘hbr’ (to include channels measuring deoxyhemoglobin).
EEG-CSD channels.
Deep brain stimulation channels.
list
of str
List of additional channels to include. If empty do not include any.
list
of str
| str
List of channels to exclude. If ‘bads’ (default), exclude channels
in info['bads']
.
list
of str
Restrict sensor channels (MEG, EEG) to this list of channel names.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
New in version 0.9.0.
Examples using pick_types
:
The Epochs data structure: discontinuous data
Compute effect-matched-spatial filtering (EMS)
Linear classifier on sensor data with plot patterns and filters
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.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick good data channels. Note that channels
in info['bads']
will be included if their names or indices are
explicitly provided.
dict
| None
Scaling factors for the traces. If a dictionary where any
value is 'auto'
, the scaling factor is set to match the 99.5th
percentile of the respective data. If 'auto'
, all scalings (for all
channel types) are set to 'auto'
. If any values are 'auto'
and the
data is not preloaded, a subset up to 100 MB will be loaded. If None
,
defaults to:
dict(mag=1e-12, grad=4e-11, eeg=20e-6, eog=150e-6, ecg=5e-4,
emg=1e-3, ref_meg=1e-12, misc=1e-3, stim=1,
resp=1, chpi=1e-4, whitened=1e2)
Note
A particular scaling value s
corresponds to half of the visualized
signal range around zero (i.e. from 0
to +s
or from 0
to
-s
). For example, the default scaling of 20e-6
(20µV) for EEG
signals means that the visualized range will be 40 µV (20 µV in the
positive direction and 20 µV in the negative direction).
int
The number of epochs per view. Defaults to 20.
int
The number of channels per view. Defaults to 20.
str
| None
The title of the window. If None, epochs name will be displayed. Defaults to None.
None
| array
, shape (n_events, 3)Events to show with vertical bars. You can use plot_events
as a legend for the colors. By default, the coloring scheme is the
same. Defaults to None
.
Warning
If the epochs have been resampled, the events no longer align with the data.
New in version 0.14.0.
dict
| None
Color(s) to use for events. To show all events in the same
color, pass any matplotlib-compatible color. To color events differently,
pass a dict
that maps event names or integer event numbers to colors
(must include entries for all events, or include a “fallback” entry with
key -1
). If None
, colors are chosen from the current Matplotlib
color cycle.
Defaults to None
.
array
of str
| None
Order in which to plot channel types.
New in version 0.18.0.
Show figure if True. Defaults to True.
Whether to halt program execution until the figure is closed. Useful for rejecting bad trials on the fly by clicking on an epoch. Defaults to False.
int
| ‘auto’Amount to decimate the data during display for speed purposes.
You should only decimate if the data are sufficiently low-passed,
otherwise aliasing can occur. The ‘auto’ mode (default) uses
the decimation that results in a sampling rate at least three times
larger than info['lowpass']
(e.g., a 40 Hz lowpass will result in
at least a 120 Hz displayed sample rate).
New in version 0.15.0.
Covariance
| str
| None
Noise covariance used to whiten the data while plotting.
Whitened data channels are scaled by scalings['whitened']
,
and their channel names are shown in italic.
Can be a string to load a covariance from disk.
See also mne.Evoked.plot_white()
for additional inspection
of noise covariance properties when whitening evoked data.
For data processed with SSS, the effective dependence between
magnetometers and gradiometers may introduce differences in scaling,
consider using mne.Evoked.plot_white()
.
New in version 0.16.0.
Whether to directly call the butterfly view.
New in version 0.18.0.
Whether to show scrollbars when the plot is initialized. Can be toggled
after initialization by pressing z (“zen mode”) while the plot
window is focused. Default is True
.
New in version 0.19.0.
Whether to show scale bars when the plot is initialized. Can be toggled
after initialization by pressing s while the plot window is focused.
Default is True
.
New in version 0.24.0.
list
of (n_epochs) list
(of n_channels) | None
Colors to use for individual epochs. If None, use default colors.
dict
| None
Dictionary of event labels (e.g. ‘aud_l’) as keys and associated event
integers as values. Useful when events
contains event numbers not
present in epochs.event_id
(e.g., because of event subselection).
Values in event_id
will take precedence over those in
epochs.event_id
when there are overlapping keys.
New in version 0.20.
str
How to group channels. 'type'
groups by channel type,
'original'
plots in the order of ch_names, 'selection'
uses
Elekta’s channel groupings (only works for Neuromag data),
'position'
groups the channels by the positions of the sensors.
'selection'
and 'position'
modes allow custom selections by
using a lasso selector on the topomap. In butterfly mode, 'type'
and 'original'
group the channels by type, whereas 'selection'
and 'position'
use regional grouping. 'type'
and 'original'
modes are ignored when order
is not None
. Defaults to 'type'
.
str
Whether to load all data (not just the visible portion) into RAM and
apply preprocessing (e.g., projectors) to the full data array in a separate
processor thread, instead of window-by-window during scrolling. The default
None uses the MNE_BROWSER_PRECOMPUTE
variable, which defaults to
'auto'
. 'auto'
compares available RAM space to the expected size of
the precomputed data, and precomputes only if enough RAM is available.
This is only used with the Qt backend.
New in version 0.24.
Changed in version 1.0: Support for the MNE_BROWSER_PRECOMPUTE config variable.
None
Whether to use OpenGL when rendering the plot (requires pyopengl
).
May increase performance, but effect is dependent on system CPU and
graphics hardware. Only works if using the Qt backend. Default is
None, which will use False unless the user configuration variable
MNE_BROWSER_USE_OPENGL
is set to 'true'
,
see mne.set_config()
.
New in version 0.24.
str
| path-likeCan be “auto”, “light”, or “dark” or a path-like to a
custom stylesheet. For Dark-Mode and automatic Dark-Mode-Detection,
qdarkstyle
and
darkdetect,
respectively, are required. If None (default), the config option MNE_BROWSER_THEME will be used,
defaulting to “auto” if it’s not found.
Only supported by the 'qt'
backend.
New in version 1.0.
str
| None
Can be “channels”, “empty”, or “hidden” to set the overview bar mode
for the 'qt'
backend. If None (default), the config option
MNE_BROWSER_OVERVIEW_MODE
will be used, defaulting to “channels”
if it’s not found.
New in version 1.1.
matplotlib.figure.Figure
| mne_qt_browser.figure.MNEQtBrowserBrowser instance.
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. h
key plots a histogram of
peak-to-peak values along with the used rejection thresholds. Butterfly
plot can be toggled with b
key. Left mouse click adds a vertical line
to the plot. Click ‘help’ button at bottom left corner of the plotter to
view all the options.
New in version 0.10.0.
Examples using plot
:
Rejecting bad data spans and breaks
The Epochs data structure: discontinuous data
EEG analysis - Event-Related Potentials (ERPs)
Show the channel stats based on a drop_log from Epochs.
float
The percentage threshold to use to decide whether or not to plot. Default is zero (always plot).
int
Maximum number of channels to show stats for.
str
| None
The subject name to use in the title of the plot. If None
, do not
display a subject name.
Changed in version 0.23: Added support for None
.
Changed in version 1.0: Defaults to None
.
tuple
| str
Color to use for the bars.
float
Width of the bars.
list
The drop reasons to ignore.
Show figure if True.
matplotlib.figure.Figure
The figure.
Examples using plot_drop_log
:
Rejecting bad data spans and breaks
Preprocessing functional near-infrared spectroscopy (fNIRS) data
EEG analysis - Event-Related Potentials (ERPs)
Plot Event Related Potential / Fields image.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick good data channels. Note that channels
in info['bads']
will be included if their names or indices are
explicitly provided.
picks
interacts with group_by
and combine
to determine the
number of figures generated; see Notes.
float
The standard deviation of a Gaussian smoothing window applied along the epochs axis of the image. If 0, no smoothing is applied. Defaults to 0.
None
| float
| callable()
The min value in the image (and the ER[P/F]). The unit is µV for
EEG channels, fT for magnetometers and fT/cm for gradiometers.
If vmin is None and multiple plots are returned, the limit is
equalized within channel types.
Hint: to specify the lower limit of the data, use
vmin=lambda data: data.min()
.
None
| float
| callable()
The max value in the image (and the ER[P/F]). The unit is µV for EEG channels, fT for magnetometers and fT/cm for gradiometers. If vmin is None and multiple plots are returned, the limit is equalized within channel types.
Display or not a colorbar.
None
| array
of int
| callable()
If not None
, order is used to reorder the epochs along the y-axis
of the image. If it is an array of int
, its length should
match the number of good epochs. If it is a callable it should accept
two positional parameters (times
and data
, where
data.shape == (len(good_epochs), len(times))
) and return an
array
of indices that will sort data
along
its first axis.
Show figure if True.
dict
| None
The units of the channel types used for axes labels. If None,
defaults to units=dict(eeg='µV', grad='fT/cm', mag='fT')
.
dict
| None
The scalings of the channel types to be applied for plotting.
If None, defaults to scalings=dict(eeg=1e6, grad=1e13, mag=1e15,
eog=1e6)
.
None
| colormap | (colormap, bool) | ‘interactive’Colormap. If tuple, the first value indicates the colormap to use and the second value is a boolean defining interactivity. In interactive mode the colors are adjustable by clicking and dragging the colorbar with left and right mouse button. Left mouse button moves the scale up and down and right mouse button adjusts the range. Hitting space bar resets the scale. Up and down arrows can be used to change the colormap. If ‘interactive’, translates to (‘RdBu_r’, True). If None, “RdBu_r” is used, unless the data is all positive, in which case “Reds” is used.
Figure
| None
Figure
instance to draw the image to.
Figure must contain the correct number of axes for drawing the epochs
image, the evoked response, and a colorbar (depending on values of
evoked
and colorbar
). If None
a new figure is created.
Defaults to None
.
list
of Axes
| dict
of list
of Axes
| None
List of Axes
objects in which to draw the
image, evoked response, and colorbar (in that order). Length of list
must be 1, 2, or 3 (depending on values of colorbar
and evoked
parameters). If a dict
, each entry must be a list of Axes
objects with the same constraints as above. If both axes
and
group_by
are dicts, their keys must match. Providing non-None
values for both fig
and axes
results in an error. Defaults to
None
.
None
Times (in seconds) at which to draw a line on the corresponding row of
the image (e.g., a reaction time associated with each epoch). Note that
overlay_times
should be ordered to correspond with the
Epochs
object (i.e., overlay_times[0]
corresponds to
epochs[0]
, etc).
None
| str
| callable()
How to combine information across channels. If a str
, must be
one of ‘mean’, ‘median’, ‘std’ (standard deviation) or ‘gfp’ (global
field power).
If callable, the callable must accept one positional input (data of
shape (n_epochs, n_channels, n_times)
) and return an
array
of shape (n_epochs, n_times)
. For
example:
combine = lambda data: np.median(data, axis=1)
If combine
is None
, channels are combined by computing GFP,
unless group_by
is also None
and picks
is a list of
specific channels (not channel types), in which case no combining is
performed and each channel gets its own figure. See Notes for further
details. Defaults to None
.
None
| dict
Specifies which channels are aggregated into a single figure, with
aggregation method determined by the combine
parameter. If not
None
, one Figure
is made per dict
entry; the dict key will be used as the figure title and the dict
values must be lists of picks (either channel names or integer indices
of epochs.ch_names
). For example:
group_by=dict(Left_ROI=[1, 2, 3, 4], Right_ROI=[5, 6, 7, 8])
Note that within a dict entry all channels must have the same type.
group_by
interacts with picks
and combine
to determine the
number of figures generated; see Notes. Defaults to None
.
Draw the ER[P/F] below the image or not.
None
| dict
Arguments passed to a call to plot_compare_evokeds
to style
the evoked plot below the image. Defaults to an empty dictionary,
meaning plot_compare_evokeds
will be called with default
parameters.
None
| str
If str
, will be plotted as figure title. Otherwise, the
title will indicate channel(s) or channel type being plotted. Defaults
to None
.
Whether to clear the axes before plotting (if fig
or axes
are
provided). Defaults to False
.
Notes
You can control how channels are aggregated into one figure or plotted in
separate figures through a combination of the picks
, group_by
, and
combine
parameters. If group_by
is a dict
, the result is
one Figure
per dictionary key (for any valid
values of picks
and combine
). If group_by
is None
, the
number and content of the figures generated depends on the values of
picks
and combine
, as summarized in this table:
group_by |
picks |
combine |
result |
---|---|---|---|
dict |
None, int, list of int, ch_name, list of ch_names, ch_type, list of ch_types |
None, string, or callable |
1 figure per dict key |
None |
None, ch_type, list of ch_types |
None, string, or callable |
1 figure per ch_type |
int, ch_name, list of int, list of ch_names |
None |
1 figure per pick |
|
string or callable |
1 figure |
Examples using plot_image
:
Overview of MEG/EEG analysis with MNE-Python
Overview of artifact detection
Rejecting bad data spans and breaks
Divide continuous data into equally-spaced epochs
Plot single trial activity, grouped by ROI and sorted by RT
Plot SSP vector.
None
| list
The channel type to plot. For ‘grad’, the gradiometers are collec- ted in pairs and the RMS for each pair is plotted. If None (default), it will return all channel types present. If a list of ch_types is provided, it will return multiple figures.
None
Colormap to use. If tuple, the first value indicates the colormap to
use and the second value is a boolean defining interactivity. In
interactive mode (only works if colorbar=True
) the colors are
adjustable by clicking and dragging the colorbar with left and right
mouse button. Left mouse button moves the scale up and down and right
mouse button adjusts the range. Hitting space bar resets the range. Up
and down arrows can be used to change the colormap. If None (default),
‘Reds’ is used for all positive data, otherwise defaults to ‘RdBu_r’.
If ‘interactive’, translates to (None, True).
str
Add markers for sensor locations to the plot. Accepts matplotlib plot format string (e.g., ‘r+’ for red plusses). If True, a circle will be used (via .add_artist). Defaults to True.
Plot a colorbar.
int
The resolution of the topomap image (n pixels along each side).
Side length of the topomaps in inches (only applies when plotting multiple topomaps at a time).
Show figure if True.
dict
| None
The outlines to be drawn. If ‘head’, the default head scheme will be drawn. If ‘skirt’ the head scheme will be drawn, but sensors are allowed to be plotted outside of the head circle. If dict, each key refers to a tuple of x and y positions, the values in ‘mask_pos’ will serve as image mask. Alternatively, a matplotlib patch object can be passed for advanced masking options, either directly or as a function that returns patches (required for multi-axis plots). If None, nothing will be drawn. Defaults to ‘head’.
int
| array
of float
The number of contour lines to draw. If 0, no contours will be drawn. When an integer, matplotlib ticker locator is used to find suitable values for the contour thresholds (may sometimes be inaccurate, use array for accuracy). If an array, the values represent the levels for the contours. Defaults to 6.
str
The image interpolation to be used. Options are 'cubic'
(default)
to use scipy.interpolate.CloughTocher2DInterpolator
,
'nearest'
to use scipy.spatial.Voronoi
or
'linear'
to use scipy.interpolate.LinearNDInterpolator
.
Axes
| list
| None
The axes to plot to. If list, the list must be a list of Axes of the same length as the number of projectors. If instance of Axes, there must be only one projector. Defaults to None.
tuple
of length 2 | ‘joint’Colormap limits to use. If tuple
, specifies the lower and
upper bounds of the colormap (in that order); providing None
for
either of these will set the corresponding boundary at the min/max of
the data (separately for each projector). The keyword value 'joint'
will compute the colormap limits jointly across all provided
projectors of the same channel type, using the min/max of the projector
data. If vlim is 'joint'
, info
must not be None
. Defaults
to (None, None)
.
float
| array-like | instance of ConductorModel
| None
| ‘auto’ | ‘eeglab’The sphere parameters to use for the head outline. Can be array-like of
shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
to give just the radius (origin assumed 0, 0, 0). Can also be an instance
of a spherical ConductorModel
to use the origin and
radius from that object. If 'auto'
the sphere is fit to digitization
points. If 'eeglab'
the head circle is defined by EEG electrodes
'Fpz'
, 'Oz'
, 'T7'
, and 'T8'
(if 'Fpz'
is not present,
it will be approximated from the coordinates of 'Oz'
). None
(the
default) is equivalent to 'auto'
when enough extra digitization points
are available, and (0, 0, 0, 0.095) otherwise. Currently the head radius
does not affect plotting.
New in version 0.20.
Changed in version 1.1: Added 'eeglab'
option.
str
The image interpolation to be used. Options are 'cubic'
(default)
to use scipy.interpolate.CloughTocher2DInterpolator
,
'nearest'
to use scipy.spatial.Voronoi
or
'linear'
to use scipy.interpolate.LinearNDInterpolator
.
str
Options:
'box'
Extrapolate to four points placed to form a square encompassing all data points, where each side of the square is three times the range of the data in the respective dimension.
'local'
(default for MEG sensors)Extrapolate only to nearby points (approximately to points closer than median inter-electrode distance). This will also set the mask to be polygonal based on the convex hull of the sensors.
'head'
(default for non-MEG sensors)Extrapolate out to the edges of the clipping circle. This will be on the head circle when the sensors are contained within the head circle, but it can extend beyond the head when sensors are plotted outside the head circle.
Changed in version 0.21:
The default was changed to 'local'
for MEG sensors.
'local'
was changed to use a convex hull mask
'head'
was changed to extrapolate out to the clipping circle.
New in version 0.20.
float
| ‘mean’Value to extrapolate to on the topomap borders. If 'mean'
(default),
then each extrapolated point has the average value of its neighbours.
New in version 0.20.
Figure
Figure distributing one image per channel across sensor topography.
Examples using plot_projs_topomap
:
The Epochs data structure: discontinuous data
Plot the power spectral density across channels.
Different channel types are drawn in sub-plots. When the data have been processed with a bandpass, lowpass or highpass filter, dashed lines (╎) indicate the boundaries of the filter. The line noise frequency is also indicated with a dashed line (⋮).
float
Start frequency to consider.
float
End frequency to consider.
float
| None
Start time to consider.
float
| None
End time to consider.
Apply projection.
float
The bandwidth of the multi taper windowing function in Hz. The default value is a window half-bandwidth of 4.
Use adaptive weights to combine the tapered spectra into PSD (slow, use n_jobs >> 1 to speed up computation).
Only use tapers with more than 90% spectral concentration within bandwidth.
Normalization strategy. If “full”, the PSD will be normalized by the
sampling rate as well as the length of the signal (as in
Nitime). Default is 'length'
.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings
(e.g., ['meg', 'eeg']
) will pick channels of those
types, channel name strings (e.g., ['MEG0111', 'MEG2623']
will pick the given channels. Can also be the string values
“all” to pick all channels, or “data” to pick data channels.
None (default) will pick good data channels. Note that channels in info['bads']
will be included if their names or indices are explicitly provide
Cannot be None if ax
is supplied.If both picks
and ax
are None
separate subplots will be created for each standard channel type
(mag
, grad
, and eeg
).
Axes
| None
Axes to plot into. If None, axes will be created.
str
| tuple
A matplotlib-compatible color to use. Has no effect when spatial_colors=True.
str
Can be ‘linear’ (default) or ‘log’.
str
| None
Mode for plotting area. If ‘std’, the mean +/- 1 STD (across channels) will be plotted. If ‘range’, the min and max (across channels) will be plotted. Bad channels will be excluded from these calculations. If None, no area will be plotted. If average=False, no area is plotted.
float
Alpha for the area.
Plot Power Spectral Density (PSD), in units (amplitude**2/Hz (dB)) if
dB=True
, and estimate='power'
or estimate='auto'
. Plot PSD
in units (amplitude**2/Hz) if dB=False
and,
estimate='power'
. Plot Amplitude Spectral Density (ASD), in units
(amplitude/sqrt(Hz)), if dB=False
and estimate='amplitude'
or
estimate='auto'
. Plot ASD, in units (amplitude/sqrt(Hz) (db)), if
dB=True
and estimate='amplitude'
.
str
, {‘auto’, ‘power’, ‘amplitude’}Can be “power” for power spectral density (PSD), “amplitude” for amplitude spectrum density (ASD), or “auto” (default), which uses “power” when dB is True and “amplitude” otherwise.
Show the figure if True
.
int
| None
The number of jobs to run in parallel. If -1
, it is set
to the number of CPU cores. Requires the joblib
package.
None
(default) is a marker for ‘unset’ that will be interpreted
as n_jobs=1
(sequential execution) unless the call is performed under
a joblib.parallel_backend()
context manager that sets another
value for n_jobs
.
If False, the PSDs of all channels is displayed. No averaging is done and parameters area_mode and area_alpha are ignored. When False, it is possible to paint an area (hold left mouse button and drag) to plot a topomap.
float
| None
Alpha for the PSD line. Can be None (default) to use 1.0 when
average=True
and 0.1 when average=False
.
Whether to use spatial colors. Only used when average=False
.
float
| array-like | instance of ConductorModel
| None
| ‘auto’ | ‘eeglab’The sphere parameters to use for the head outline. Can be array-like of
shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
to give just the radius (origin assumed 0, 0, 0). Can also be an instance
of a spherical ConductorModel
to use the origin and
radius from that object. If 'auto'
the sphere is fit to digitization
points. If 'eeglab'
the head circle is defined by EEG electrodes
'Fpz'
, 'Oz'
, 'T7'
, and 'T8'
(if 'Fpz'
is not present,
it will be approximated from the coordinates of 'Oz'
). None
(the
default) is equivalent to 'auto'
when enough extra digitization points
are available, and (0, 0, 0, 0.095) otherwise. Currently the head radius
does not affect plotting.
New in version 0.20.
Changed in version 1.1: Added 'eeglab'
option.
list
of str
| ‘bads’Channels names to exclude from being shown. If ‘bads’, the bad channels are excluded. Pass an empty list to plot all channels (including channels marked “bad”, if any).
New in version 0.24.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Figure
Figure with frequency spectra of the data channels.
Examples using plot_psd
:
The Epochs data structure: discontinuous data
Frequency and time-frequency sensor analysis
Plot the topomap of the power spectral density across epochs.
list
of tuple
| None
The frequencies or frequency ranges to plot. Length-2 tuples specify
a single frequency and a subplot title (e.g.,
(6.5, 'presentation rate')
); length-3 tuples specify lower and
upper band edges and a subplot title. If None
(the default),
expands to:
bands = [(0, 4, 'Delta'), (4, 8, 'Theta'), (8, 12, 'Alpha'),
(12, 30, 'Beta'), (30, 45, 'Gamma')]
In bands where a single frequency is provided, the topomap will reflect the single frequency bin that is closest to the provided value.
float
| None
Start time to consider.
float
| None
End time to consider.
Apply projection.
float
The bandwidth of the multi taper windowing function in Hz. The default value is a window half-bandwidth of 4 Hz.
Use adaptive weights to combine the tapered spectra into PSD (slow, use n_jobs >> 1 to speed up computation).
Only use tapers with more than 90% spectral concentration within bandwidth.
Normalization strategy. If “full”, the PSD will be normalized by the
sampling rate as well as the length of the signal (as in
Nitime). Default is 'length'
.
None
The channel type to plot. For ‘grad’, the gradiometers are collected in pairs and the mean for each pair is plotted. If None, then first available channel type from order given above is used. Defaults to None.
None
Colormap to use. If tuple
, the first value indicates the colormap
to use and the second value is a boolean defining interactivity. In
interactive mode the colors are adjustable by clicking and dragging the
colorbar with left and right mouse button. Left mouse button moves the
scale up and down and right mouse button adjusts the range. Hitting
space bar resets the range. Up and down arrows can be used to change
the colormap. If None
, 'Reds'
is used for data that is either
all-positive or all-negative, and 'RdBu_r'
is used otherwise.
'interactive'
is equivalent to (None, True)
. Defaults to None
.
callable()
The function used to aggregate over frequencies. Defaults to
numpy.sum()
if normalize=True
, else numpy.mean()
.
If True
, transform data to decibels (with 10 * np.log10(data)
)
following the application of agg_fun
. Ignored if normalize=True
.
int
| None
The number of jobs to run in parallel. If -1
, it is set
to the number of CPU cores. Requires the joblib
package.
None
(default) is a marker for ‘unset’ that will be interpreted
as n_jobs=1
(sequential execution) unless the call is performed under
a joblib.parallel_backend()
context manager that sets another
value for n_jobs
.
If True, each band will be divided by the total power. Defaults to False.
str
Format string for the colorbar tick labels. If 'auto'
, is equivalent
to ‘%0.3f’ if dB=False
and ‘%0.1f’ if dB=True
. Defaults to
'auto'
.
dict
| None
The outlines to be drawn. If ‘head’, the default head scheme will be drawn. If ‘skirt’ the head scheme will be drawn, but sensors are allowed to be plotted outside of the head circle. If dict, each key refers to a tuple of x and y positions, the values in ‘mask_pos’ will serve as image mask. Alternatively, a matplotlib patch object can be passed for advanced masking options, either directly or as a function that returns patches (required for multi-axis plots). If None, nothing will be drawn. Defaults to ‘head’.
list
of Axes
| None
List of axes to plot consecutive topographies to. If None
the axes
will be created automatically. Defaults to None
.
Show figure if True.
float
| array-like | instance of ConductorModel
| None
| ‘auto’ | ‘eeglab’The sphere parameters to use for the head outline. Can be array-like of
shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
to give just the radius (origin assumed 0, 0, 0). Can also be an instance
of a spherical ConductorModel
to use the origin and
radius from that object. If 'auto'
the sphere is fit to digitization
points. If 'eeglab'
the head circle is defined by EEG electrodes
'Fpz'
, 'Oz'
, 'T7'
, and 'T8'
(if 'Fpz'
is not present,
it will be approximated from the coordinates of 'Oz'
). None
(the
default) is equivalent to 'auto'
when enough extra digitization points
are available, and (0, 0, 0, 0.095) otherwise. Currently the head radius
does not affect plotting.
New in version 0.20.
Changed in version 1.1: Added 'eeglab'
option.
tuple
of length 2 | ‘joint’Colormap limits to use. If a tuple
of floats, specifies the
lower and upper bounds of the colormap (in that order); providing
None
for either entry will set the corresponding boundary at the
min/max of the data (separately for each topomap). Elements of the
tuple
may also be callable functions which take in a
NumPy array
and return a scalar.
If vlim='joint'
, will compute the colormap limits jointly across
all topomaps of the same channel type, using the min/max of the data.
Defaults to (None, None)
.
New in version 0.21.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Figure
Figure distributing one image per channel across sensor topography.
Examples using plot_psd_topomap
:
The Epochs data structure: discontinuous data
Frequency and time-frequency sensor analysis
Plot sensor positions.
str
Whether to plot the sensors as 3d, topomap or as an interactive sensor selection dialog. Available options ‘topomap’, ‘3d’, ‘select’. If ‘select’, a set of channels can be selected interactively by using lasso selector or clicking while holding control key. The selected channels are returned along with the figure instance. Defaults to ‘topomap’.
None
| str
The channel type to plot. Available options ‘mag’, ‘grad’, ‘eeg’,
‘seeg’, ‘dbs’, ‘ecog’, ‘all’. If 'all'
, all the available mag,
grad, eeg, seeg, dbs, and ecog channels are plotted. If
None (default), then channels are chosen in the order given above.
str
| None
Title for the figure. If None (default), equals to 'Sensor
positions (%s)' % ch_type
.
array
of str
Whether to display all channel names. If an array, only the channel names in the array are shown. Defaults to False.
array
of shape (n_ch_groups, n_picks) | None
Channel groups for coloring the sensors. If None (default), default
coloring scheme is used. If ‘position’, the sensors are divided
into 8 regions. See order
kwarg of mne.viz.plot_raw()
. If
array, the channels are divided by picks given in the array.
New in version 0.13.0.
Whether to project the 3d locations to a sphere. When False, the sensor array appears similar as to looking downwards straight above the subject’s head. Has no effect when kind=’3d’. Defaults to True.
New in version 0.14.0.
Axes
| instance of Axes3D
| None
Axes to draw the sensors to. If kind='3d'
, axes must be an
instance of Axes3D. If None (default), a new axes will be created.
New in version 0.13.0.
Whether to halt program execution until the figure is closed. Defaults to False.
New in version 0.13.0.
Show figure if True. Defaults to True.
float
| array-like | instance of ConductorModel
| None
| ‘auto’ | ‘eeglab’The sphere parameters to use for the head outline. Can be array-like of
shape (4,) to give the X/Y/Z origin and radius in meters, or a single float
to give just the radius (origin assumed 0, 0, 0). Can also be an instance
of a spherical ConductorModel
to use the origin and
radius from that object. If 'auto'
the sphere is fit to digitization
points. If 'eeglab'
the head circle is defined by EEG electrodes
'Fpz'
, 'Oz'
, 'T7'
, and 'T8'
(if 'Fpz'
is not present,
it will be approximated from the coordinates of 'Oz'
). None
(the
default) is equivalent to 'auto'
when enough extra digitization points
are available, and (0, 0, 0, 0.095) otherwise. Currently the head radius
does not affect plotting.
New in version 0.20.
Changed in version 1.1: Added 'eeglab'
option.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
This function plots the sensor locations from the info structure using
matplotlib. For drawing the sensors using PyVista see
mne.viz.plot_alignment()
.
New in version 0.12.0.
Examples using plot_sensors
:
Plot Event Related Potential / Fields image on topographies.
Layout
System specific sensor positions.
float
The standard deviation of the Gaussian smoothing to apply along the epoch axis to apply in the image. If 0., no smoothing is applied.
float
The min value in the image. The unit is µV for EEG channels, fT for magnetometers and fT/cm for gradiometers.
float
The max value in the image. The unit is µV for EEG channels, fT for magnetometers and fT/cm for gradiometers.
None
Whether to display a colorbar or not. If None
a colorbar will be
shown only if all channels are of the same type. Defaults to None
.
None
| array
of int
| callable()
If not None, order is used to reorder the epochs on the y-axis of the image. If it’s an array of int it should be of length the number of good epochs. If it’s a callable the arguments passed are the times vector and the data as 2d array (data.shape[1] == len(times)).
Colors to be mapped to the values.
float
Scaling factor for adjusting the relative size of the layout on the canvas.
str
Title of the figure.
dict
| None
The scalings of the channel types to be applied for plotting. If
None
, defaults to dict(eeg=1e6, grad=1e13, mag=1e15)
.
str
Matplotlib borders style to be used for each sensor plot.
The figure face color. Defaults to black.
None
| array
A background image for the figure. This must be a valid input to
matplotlib.pyplot.imshow()
. Defaults to None
.
The color of tick labels in the colorbar. Defaults to white.
Whether to show the figure. Defaults to True
.
matplotlib.figure.Figure
Figure distributing one image per channel across sensor topography.
Notes
In an interactive Python session, this plot will be interactive; clicking on a channel image will pop open a larger view of the image; this image will always have a colorbar even when the topo plot does not (because it shows multiple sensor types).
Whether or not projections are active.
Rename channels.
dict
| callable()
A dictionary mapping the old channel to a new channel name e.g. {‘EEG061’ : ‘EEG161’}. Can also be a callable function that takes and returns a string.
Changed in version 0.10.0: Support for a callable function.
If True (default False), allow duplicates, which will automatically
be renamed with -N
at the end.
New in version 0.22.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
New in version 0.9.0.
Examples using rename_channels
:
The Epochs data structure: discontinuous data
Reorder channels.
list
The desired channel order.
See also
Notes
Channel names must be unique. Channels that are not in ch_names
are dropped.
New in version 0.16.0.
Examples using reorder_channels
:
The Epochs data structure: discontinuous data
Resample data.
If appropriate, an anti-aliasing filter is applied before resampling. See Resampling and decimating data for more information.
Note
Data must be loaded.
float
New sample rate to use.
int
| str
Amount to pad the start and end of the data. Can also be “auto” to use a padding that will result in a power-of-two size (can be much faster).
str
| tuple
Frequency-domain window to use in resampling.
See scipy.signal.resample()
.
int
| str
Number of jobs to run in parallel. Can be ‘cuda’ if cupy
is installed properly.
str
The type of padding to use. Supports all numpy.pad()
mode
options. Can also be "reflect_limited"
, which pads with a
reflected version of each vector mirrored on the first and last values
of the vector, followed by zeros.
The default is 'edge'
, which pads with the edge values of each
vector.
New in version 0.15.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
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!
Examples using resample
:
The Epochs data structure: discontinuous data
Reset the drop_log and selection entries.
This method will simplify self.drop_log
and self.selection
so that they are meaningless (tuple of empty tuples and increasing
integers, respectively). This can be useful when concatenating
many Epochs instances, as drop_log
can accumulate many entries
which can become problematic when saving.
Save epochs in a fif file.
str
The name of the file, which should end with -epo.fif
or
-epo.fif.gz
.
str
| int
Large raw files are automatically split into multiple pieces. This parameter specifies the maximum size of each piece. If the parameter is an integer, it specifies the size in Bytes. It is also possible to pass a human-readable string, e.g., 100MB. Note: Due to FIFF file limitations, the maximum split size is 2GB.
New in version 0.10.0.
str
Format to save data. Valid options are ‘double’ or ‘single’ for 64- or 32-bit float, or for 128- or 64-bit complex numbers respectively. Note: Data are processed with double precision. Choosing single-precision, the saved data will slightly differ due to the reduction in precision.
New in version 0.17.
If True (default False), overwrite the destination file if it exists. To overwrite original file (the same one that was loaded), data must be preloaded upon reading. This defaults to True in 0.18 but will change to False in 0.19.
New in version 0.18.
When splitting files, append a filename partition with the appropriate
naming schema: for 'neuromag'
, a split file fname.fif
will be named
fname.fif
, fname-1.fif
, fname-2.fif
etc.; while for 'bids'
,
it will be named fname_split-01.fif
, fname_split-02.fif
, etc.
New in version 0.24.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
Bad epochs will be dropped before saving the epochs to disk.
Examples using save
:
The Epochs data structure: discontinuous data
Filter the data using Savitzky-Golay polynomial method.
float
Approximate high cut-off frequency in Hz. Note that this is not an exact cutoff, since Savitzky-Golay filtering [3] is done using polynomial fits instead of FIR/IIR filtering. This parameter is thus used to determine the length of the window over which a 5th-order polynomial smoothing is used.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
For Savitzky-Golay low-pass approximation, see:
New in version 0.9.0.
References
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()
Setter for Epoch annotations from Raw.
This method does not handle offsetting the times based on first_samp or measurement dates, since that is expected to occur in Raw.set_annotations().
mne.Annotations
| None
Annotations to set.
Can be 'raise'
(default) to raise an error, 'warn'
to emit a
warning, or 'ignore'
to ignore when entries in ch_names are not present in the raw instance.
New in version 0.23.0.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Epochs
The epochs object with annotations.
Notes
Annotation onsets and offsets are stored as time in seconds (not as sample numbers).
If you have an -epo.fif
file saved to disk created before 1.0,
annotations can be added correctly only if no decimation or
resampling was performed. We thus suggest to regenerate your
mne.Epochs
from raw and re-save to disk with 1.0+ if you
want to safely work with Annotations
in epochs.
Since this method does not handle offsetting the times based on first_samp or measurement dates, the recommended way to add Annotations is:
raw.set_annotations(annotations)
annotations = raw.annotations
epochs.set_annotations(annotations)
New in version 1.0.
Define the sensor type of channels.
dict
A dictionary mapping a channel to a sensor type (str), e.g.,
{'EEG061': 'eog'}
.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
Notes
The following sensor types are accepted:
ecg, eeg, emg, eog, exci, ias, misc, resp, seeg, dbs, stim, syst, ecog, hbo, hbr, fnirs_cw_amplitude, fnirs_fd_ac_amplitude, fnirs_fd_phase, fnirs_od
New in version 0.9.0.
Examples using set_channel_types
:
The Epochs data structure: discontinuous data
Specify which reference to use for EEG data.
Use this function to explicitly specify the desired reference for EEG. This can be either an existing electrode or a new virtual channel. This function will re-reference the data according to the desired reference.
list
of str
| str
Can be:
The name(s) of the channel(s) used to construct the reference.
'average'
to apply an average reference (default)
'REST'
to use the Reference Electrode Standardization Technique
infinity reference [4].
An empty list, in which case MNE will not attempt any re-referencing of the data
If ref_channels='average'
this argument specifies if the
average reference should be computed as a projection (True) or not
(False; default). If projection=True
, the average reference is
added as a projection and is not applied to the data (it can be
applied afterwards with the apply_proj
method). If
projection=False
, the average reference is directly applied to
the data. If ref_channels
is not 'average'
, projection
must be set to False
(the default in this case).
list
of str
| str
The name of the channel type to apply the reference to.
Valid channel types are 'auto'
, 'eeg'
, 'ecog'
, 'seeg'
,
'dbs'
. If 'auto'
, the first channel type of eeg, ecog, seeg or dbs
that is found (in that order) will be selected.
New in version 0.19.
Forward
| None
Forward solution to use. Only used with ref_channels='REST'
.
New in version 0.21.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
mne.set_bipolar_reference
Convenience function for creating bipolar references.
Notes
Some common referencing schemes and the corresponding value for the
ref_channels
parameter:
A new virtual reference electrode is created by averaging the current
EEG signal by setting ref_channels='average'
. Bad EEG channels are
automatically excluded if they are properly set in info['bads']
.
Set ref_channels
to a list containing the name of the channel that
will act as the new reference, for example ref_channels=['Cz']
.
A new virtual reference electrode is created by computing the average
of the current EEG signal recorded from two or more selected channels.
Set ref_channels
to a list of channel names, indicating which
channels to use. For example, to apply an average mastoid reference,
when using the 10-20 naming scheme, set ref_channels=['M1', 'M2']
.
The given EEG electrodes are referenced to a point at infinity using the
lead fields in forward
, which helps standardize the signals.
If a reference is requested that is not the average reference, this function removes any pre-existing average reference projections.
During source localization, the EEG signal should have an average reference.
In order to apply a reference, the data must be preloaded. This is not
necessary if ref_channels='average'
and projection=True
.
For an average or REST reference, bad EEG channels are automatically
excluded if they are properly set in info['bads']
.
New in version 0.9.0.
References
Set the measurement start date.
datetime
| float
| tuple
| None
The new measurement date.
If datetime object, it must be timezone-aware and in UTC.
A tuple of (seconds, microseconds) or float (alias for
(meas_date, 0)
) can also be passed and a datetime
object will be automatically created. If None, will remove
the time reference.
See also
Notes
If you want to remove all time references in the file, call
mne.io.anonymize_info(inst.info)
after calling inst.set_meas_date(None)
.
New in version 0.20.
Set EEG/sEEG/ECoG/DBS/fNIRS channel positions and digitization points.
None
| str
| DigMontage
A montage containing channel positions. If a string or
DigMontage
is
specified, the existing channel information will be updated with the
channel positions from the montage. Valid strings are the names of the
built-in montages that ship with MNE-Python; you can list those via
mne.channels.get_builtin_montages()
.
If None
(default), the channel positions will be removed from the
Info
.
If True (default), channel name matching will be case sensitive.
New in version 0.20.
dict
Whether to use a lookup table to match unrecognized channel location names
to their known aliases. If True, uses the mapping in
mne.io.constants.CHANNEL_LOC_ALIASES
. If a dict
is passed, it
will be used instead, and should map from non-standard channel names to
names in the specified montage
. Default is False
.
New in version 0.23.
Can be 'raise'
(default) to raise an error, 'warn'
to emit a
warning, or 'ignore'
to ignore when channels have missing coordinates.
New in version 0.20.1.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
See also
Notes
Warning
Only EEG/sEEG/ECoG/DBS/fNIRS channels can have their positions set using a montage. Other channel types (e.g., MEG channels) should have their positions defined properly using their data reading functions.
Examples using set_montage
:
Shift time scale in epoched or evoked data.
float
The (absolute or relative) time shift in seconds. If relative
is True, positive tshift increases the time value associated with
each sample, while negative tshift decreases it.
If True, increase or decrease time values by tshift
seconds.
Otherwise, shift the time values such that the time of the first
sample equals tshift
.
The modified instance.
Notes
This method allows you to shift the time values associated with each data sample by an arbitrary amount. It does not resample the signal or change the data values in any way.
Examples using shift_time
:
The Epochs data structure: discontinuous data
Compute standard error over epochs.
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all data channels. Note that channels
in info['bads']
will be included if their names or indices are
explicitly provided.
When False
(the default) all epochs are processed together and a single
Evoked
object is returned. When True
, epochs are first
grouped by event type (as specified using the event_id
parameter) and a
list is returned containing a separate Evoked
object for each
event type. The .comment
attribute is set to the label of the event
type.
New in version 0.24.0.
Subtract an evoked response from each epoch.
Can be used to exclude the evoked response when analyzing induced activity, see e.g. [1].
Epochs
The modified instance (instance is also modified inplace).
References
David et al. “Mechanisms of evoked and induced responses in MEG/EEG”, NeuroImage, vol. 31, no. 4, pp. 1580-1591, July 2006.
Convert time to indices.
ndarray
Indices corresponding to the times supplied.
Examples using time_as_index
:
The Epochs data structure: discontinuous data
Time vector in seconds.
Last time point.
First time point.
Export data in tabular structure as a pandas DataFrame.
Channels are converted to columns in the DataFrame. By default,
additional columns “time”, “epoch” (epoch number), and “condition”
(epoch event description) are added, unless index
is not None
(in which case the columns specified in index
will be used to form
the DataFrame’s index instead).
str
| list
| slice
| None
Channels to include. Slices and lists of integers will be interpreted as
channel indices. In lists, channel type strings (e.g., ['meg',
'eeg']
) will pick channels of those types, channel name strings (e.g.,
['MEG0111', 'MEG2623']
will pick the given channels. Can also be the
string values “all” to pick all channels, or “data” to pick data
channels. None (default) will pick all channels. Note that channels in
info['bads']
will be included if their names or indices are
explicitly provided.
str
| list
of str
| None
Kind of index to use for the DataFrame. If None
, a sequential
integer index (pandas.RangeIndex
) will be used. If 'time'
, a
pandas.Float64Index
, pandas.Int64Index
, or
pandas.TimedeltaIndex
will be used
(depending on the value of time_format
). If a list of two or more string values, a pandas.MultiIndex
will be created.
Valid string values are ‘time’, ‘epoch’, and ‘condition’.
Defaults to None
.
dict
| None
Scaling factor applied to the channels picked. If None
, defaults to
dict(eeg=1e6, mag=1e15, grad=1e13)
— i.e., converts EEG to µV,
magnetometers to fT, and gradiometers to fT/cm.
If True
, data will be copied. Otherwise data may be modified in place.
Defaults to True
.
If True, the DataFrame is returned in long format where each row is one
observation of the signal at a unique combination of time point, channel, epoch number, and condition.
For convenience, a ch_type
column is added to facilitate subsetting the resulting DataFrame. Defaults to False
.
str
| None
Desired time format. If None
, no conversion is applied, and time values
remain as float values in seconds. If 'ms'
, time values will be rounded
to the nearest millisecond and converted to integers. If 'timedelta'
,
time values will be converted to pandas.Timedelta
values.
Default is None
.
New in version 0.20.
str
| int
| None
Control verbosity of the logging output. If None
, use the default
verbosity level. See the logging documentation and
mne.verbose()
for details. Should only be passed as a keyword
argument.
pandas.DataFrame
A dataframe suitable for usage with other statistical/plotting/analysis packages.
Examples using to_data_frame
:
The Epochs data structure: discontinuous data
Exporting Epochs to Pandas DataFrames
Visualising statistical significance thresholds on EEG data
mne.Epochs
#Overview of MEG/EEG analysis with MNE-Python
Getting started with mne.Report
Working with CTF data: the Brainstorm auditory dataset
Overview of artifact detection
Rejecting bad data spans and breaks
Repairing artifacts with regression
Background on projectors and projections
Preprocessing functional near-infrared spectroscopy (fNIRS) data
The Epochs data structure: discontinuous data
Regression-based baseline correction
Auto-generating Epochs metadata
Exporting Epochs to Pandas DataFrames
Divide continuous data into equally-spaced epochs
The Evoked data structure: evoked/averaged data
EEG analysis - Event-Related Potentials (ERPs)
Frequency and time-frequency sensor analysis
Frequency-tagging: Basic analysis of an SSVEP/vSSR dataset
Source localization with MNE, dSPM, sLORETA, and eLORETA
Source reconstruction using an LCMV beamformer
EEG source localization given electrode locations on an MRI
Brainstorm Elekta phantom dataset tutorial
Brainstorm CTF phantom dataset tutorial
4D Neuroimaging/BTi phantom dataset tutorial
Visualising statistical significance thresholds on EEG data
Non-parametric 1 sample cluster statistic on single trial power
Non-parametric between conditions cluster statistic on single trial power
Mass-univariate twoway repeated measures ANOVA on single trial power
Spatiotemporal permutation F-test on full sensor data
Permutation t-test on source data with spatio-temporal clustering
Repeated measures ANOVA on source data with spatio-temporal clustering
Sleep stage classification from polysomnography (PSG) data
Corrupt known signal with point spread
Getting averaging info from .fif files
Simulate raw data using subject anatomy
Generate simulated source data
Define target events based on time lag, plot evoked response
Transform EEG data using current source density (CSD)
Maxwell filter data with movement compensation
Plot sensor denoising using oversampled temporal projection
Visualize channel over epochs as an image
Whitening evoked data with a noise covariance
Plot single trial activity, grouped by ROI and sorted by RT
Compare evoked responses for different conditions
Compute a cross-spectral density (CSD) matrix
Compute Power Spectral Density of inverse solution from single epochs
Compute power and phase lock in label of the source space
Compute induced power in the source space with dSPM
Compute and visualize ERDS maps
Explore event-related dynamics for specific frequency bands
Permutation F-test on sensor data with 1D cluster level
FDR correction on T-test on sensor data
Regression on continuous data (rER[P/F])
Permutation T-test on sensor data
Motor imagery decoding from EEG data using the Common Spatial Pattern (CSP)
Decoding in time-frequency space using Common Spatial Patterns (CSP)
Representational Similarity Analysis
Continuous Target Decoding with SPoC
Decoding sensor space data with generalization across time and conditions
Analysis of evoked response using ICA and PCA reduction techniques
Compute effect-matched-spatial filtering (EMS)
Linear classifier on sensor data with plot patterns and filters
Compute Spectro-Spatial Decomposition (SSD) spatial filters
Compute MNE-dSPM inverse solution on single epochs
Compute source power using DICS beamformer
Compute evoked ERS source power using DICS, LCMV beamformer, and dSPM
Compute source power estimate by projecting the covariance with MNE
Computing source timecourses with an XFit-like multi-dipole model
Compute iterative reweighted TF-MxNE with multiscale time-frequency dictionary
Compute cross-talk functions for LCMV beamformers
Brainstorm raw (median nerve) dataset
Optically pumped magnetometer (OPM) data
From raw data to dSPM on SPM Faces dataset