Skip to main content

InvLabelTimeCourse

Namespace: INVLIB  ·  Library: Inverse Library

Python equivalent

mne.extract_label_time_course in MNE-Python.

#include <inv/inv_label_time_course.h>

class INVLIB::InvLabelTimeCourse

Extract ROI-level time courses from vertex-level source estimates.

Provides the five standard aggregation modes used in MNE-Python's extract_label_time_course():

  • mean: Simple average across vertices in the label.
  • mean_flip: Mean with sign-flip so that dominant orientation is positive.
  • pca_flip: First PCA component, flipped to align with dominant sign.
  • max: Maximum absolute value at each time point.
  • auto: mean_flip for scalar STCs.
src/examples/ex_inv_api/main.cpp
const MatrixXd labelMean = InvLabelTimeCourse::extract(stc, {v1}, "mean");      // 1 x 421
const MatrixXd labelMax = InvLabelTimeCourse::extract(stc, {v1}, "max");        // the largest |value| per sample
const MatrixXd labelFlip = InvLabelTimeCourse::extract(stc, {v1}, "mean_flip"); // signs flipped by the patch normals

Static Methods​

extract(stc, labels, sMode, bAllowEmpty)​

Extract label time courses from a source estimate.

Parameters:

  • stc : const InvSourceEstimate & Source estimate (vertices × times).

  • labels : const QList< FsLabel > & List of labels defining ROIs.

  • sMode : const QString & Aggregation mode: "mean", "mean_flip", "pca_flip", "max", "auto".

  • bAllowEmpty : bool If true, empty labels produce zero rows; if false, skip them.

Returns:

  • Eigen::MatrixXd — Matrix of shape (n_labels × n_times).

computeSignFlip(stcData)​

Compute sign-flip vector for a label based on vertex normals.

For surface source spaces, the sign of each vertex's contribution should be flipped if its normal opposes the dominant direction in the label. This ensures coherent averaging.

Parameters:

  • stcData : const Eigen::MatrixXd & Source data for the label vertices (n_verts × n_times).

Returns:

  • Eigen::VectorXd — Sign vector (+1 or -1 per vertex).

Example​

Used in examples​

ex_inv_api​

Inverse library: minimum-norm estimates, resolution matrices, label time courses, sparse solvers.

src/examples/ex_inv_api/main.cpp, line 227
const MatrixXd labelMean = InvLabelTimeCourse::extract(stc, {v1}, "mean");      // 1 x 421
const MatrixXd labelMax = InvLabelTimeCourse::extract(stc, {v1}, "max");        // the largest |value| per sample
const MatrixXd labelFlip = InvLabelTimeCourse::extract(stc, {v1}, "mean_flip"); // signs flipped by the patch normals
// mne.extract_label_time_course(stc, v1, src, mode=...): sum |tc| for "mean" 5321.19 and "max" 18182.6
ok &= expect(labelMean.rows() == 1 && near(labelMean.cwiseAbs().sum(), 5321.1945389237135, 1e-4) && near(labelMax.cwiseAbs().sum(), 18182.625800623755, 1e-4) && labelFlip.cols() == 421,
             "InvLabelTimeCourse: V1 mean and max time courses match mne.extract_label_time_course");

Authors of this file​