Extract label time course for lists of labels and source estimates.
This function will extract one time course for each label and source estimate. The way the time courses are extracted depends on the mode parameter (see Notes).
SourceEstimate
| list
(or generator) of SourceEstimate
The source estimates from which to extract the time course.
Label
| BiHemiLabel
| list
| tuple
| str
If using a surface or mixed source space, this should be the
Label
’s for which to extract the time course.
If working with whole-brain volume source estimates, this must be one of:
a string path to a FreeSurfer atlas for the subject (e.g., their ‘aparc.a2009s+aseg.mgz’) to extract time courses for all volumes in the atlas
a two-element list or tuple, the first element being a path to an atlas,
and the second being a list or dict of volume_labels
to extract
(see mne.setup_volume_source_space()
for details).
Changed in version 0.21.0: Support for volume source estimates.
SourceSpaces
The source spaces for the source time courses.
str
Extraction mode, see Notes.
str
False
(default) will emit an error if there are labels that have no
vertices in the source estimate. True
and 'ignore'
will return
all-zero time courses for labels that do not have any vertices in the
source estimate, and True will emit a warning while and “ignore” will
just log a message.
Changed in version 0.21.0: Support for “ignore”.
If True, a generator instead of a list is returned.
If True (default), the volume source space will be upsampled to the original MRI resolution via trilinear interpolation before the atlas values are extracted. This ensnures that each atlas label will contain source activations. When False, only the original source space points are used, and some atlas labels thus may not contain any source space vertices.
New in version 0.21.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
Valid values for mode
are:
'max'
Maximum value across vertices at each time point within each label.
'mean'
Average across vertices at each time point within each label. Ignores orientation of sources for standard source estimates, which varies across the cortical surface, which can lead to cancellation. Vector source estimates are always in XYZ / RAS orientation, and are thus already geometrically aligned.
'mean_flip'
Finds the dominant direction of source space normal vector orientations within each label, applies a sign-flip to time series at vertices whose orientation is more than 180° different from the dominant direction, and then averages across vertices at each time point within each label.
'pca_flip'
Applies singular value decomposition to the time courses within each label,
and uses the first right-singular vector as the representative label time
course. This signal is scaled so that its power matches the average
(per-vertex) power within the label, and sign-flipped by multiplying by
np.sign(u @ flip)
, where u
is the first left-singular vector and
flip
is the same sign-flip vector used when mode='mean_flip'
. This
sign-flip ensures that extracting time courses from the same label in
similar STCs does not result in 180° direction/phase changes.
'auto'
(default)Uses 'mean_flip'
when a standard source estimate is applied, and
'mean'
when a vector source estimate is supplied.
New in version 0.21: Support for 'auto'
, vector, and volume source estimates.
The only modes that work for vector and volume source estimates are 'mean'
,
'max'
, and 'auto'
.
If encountering a ValueError
due to mismatch between number of
source points in the subject source space and computed stc
object set
src
argument to fwd['src']
or inv['src']
to ensure the source
space is the one actually used by the inverse to compute the source
time courses.
mne.extract_label_time_course
#Compute MNE inverse solution on evoked data with a mixed source space