mne.extract_label_time_course#
- mne.extract_label_time_course(stcs, labels, src, mode='auto', allow_empty=False, return_generator=False, *, mri_resolution=True, verbose=None)[source]#
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).
- Parameters:
- stcs
SourceEstimate
|list
(or generator) ofSourceEstimate
The source estimates from which to extract the time course.
- labels
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 (seemne.setup_volume_source_space()
for details).
Changed in version 0.21.0: Support for volume source estimates.
- srcinstance of
SourceSpaces
The source spaces for the source time courses.
- mode
str
Extraction mode, see Notes.
- allow_empty
bool
|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”.
- return_generator
bool
If True, a generator instead of a list is returned.
- mri_resolution
bool
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.
- verbose
bool
|str
|int
|None
Control verbosity of the logging output. If
None
, use the default verbosity level. See the logging documentation andmne.verbose()
for details. Should only be passed as a keyword argument.
- stcs
- Returns:
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)
, whereu
is the first left-singular vector andflip
is the same sign-flip vector used whenmode='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 computedstc
object setsrc
argument tofwd['src']
orinv['src']
to ensure the source space is the one actually used by the inverse to compute the source time courses.
Examples using mne.extract_label_time_course
#
Compute MNE inverse solution on evoked data with a mixed source space