mne.extract_label_time_course

mne.extract_label_time_course(stcs, labels, src, mode='auto', allow_empty=False, return_generator=False, trans=None, 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
stcsSourceEstimate | list (or generator) of SourceEstimate

The source estimates from which to extract the time course.

labelsLabel | 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.

srcinstance of SourceSpaces

The source spaces for the source time courses.

modestr

Extraction mode, see Notes.

allow_emptybool | 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_generatorbool

If True, a generator instead of a list is returned.

transstr | dict | instance of Transform

If str, the path to the head<->MRI transform *-trans.fif file produced during coregistration. Can also be 'fsaverage' to use the built-in fsaverage transformation.

mri_resolutionbool

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.

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more). If used, it should be passed as a keyword-argument only.

Returns
label_tcarray | list (or generator) of array, shape (n_labels[, n_orient], n_times)

Extracted time course for each label and source estimate.

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.