extract_label_time_course(stcs, labels, src, mode='auto', allow_empty=False, return_generator=False, *, mri_resolution=True, verbose=None)¶
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).
list(or generator) of
The source estimates from which to extract the time course.
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_labelsto extract (see
Changed in version 0.21.0: Support for volume source estimates.
- srcinstance of
The source spaces for the source time courses.
Extraction mode, see Notes.
- allow_emptybool |
False(default) will emit an error if there are labels that have no vertices in the source estimate.
'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.
Valid values for
Maximum value across vertices at each time point within each label.
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.
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.
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
uis the first left-singular vector and
flipis 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.
'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
If encountering a
ValueErrordue to mismatch between number of source points in the subject source space and computed
inv['src']to ensure the source space is the one actually used by the inverse to compute the source time courses.