mne.extract_label_time_course

mne.extract_label_time_course(stcs, labels, src, mode='mean_flip', allow_empty=False, return_generator=False, 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 of Label or BiHemiLabel

The labels for which to extract the time course.

srclist

Source spaces for left and right hemisphere.

modestr

Extraction mode, see Notes.

allow_emptybool

Instead of emitting an error, return all-zero time courses for labels that do not have any vertices in the source estimate. Default is False.

return_generatorbool

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

verbosebool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns
label_tcarray | list (or generator) of array, shape (n_labels, 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.

  • '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.

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'] to ensure the source space is compatible between forward and inverse routines.