Skip to main content

InvConvenience

Namespace: INVLIB  ·  Library: Inverse Library

Module

This page documents a header-level module — a collection of free functions that share an algorithmic topic. There is no enclosing C++ class; the functions live directly in the library namespace.

Python equivalent

mne.minimum_norm.apply_inverse_epochs / apply_inverse_raw / apply_inverse_cov in MNE-Python.

#include <inv/inv_convenience.h>

SPDX-License-Identifier: BSD-3-Clause Copyright (c) 2026 MNE-CPP Authors.

apply_inverse_* / compute_source_psd helpers.

Free functions in this header glue together the lower-level INVLIB classes so users can match the MNE-Python ergonomics: INVLIB::applyInverseEpochs applies a precomputed inverse operator across an epoch list, applyInverseRaw streams raw data through the kernel, estimateSnr returns the whitened-data SNR trace from an evoked + inverse pair, computeWhitener produces the diagonal whitener from a noise covariance, and computeSourcePsd / computeSourceBandPower run Welch-based spectral analysis directly on InvSourceEstimate output. All methods are headers-only orchestration on top of InvMinimumNorm and the underlying FIFF / MNE primitives.

src/examples/ex_inv_api/main.cpp
// Whitened data and a gain per nAm make the noise level 1, as mne.inverse_sparse.mixed_norm does.
const auto [whitener, rank] = computeWhitener(*inverse.noise_cov); // rank 360: 364 channels minus 4 projectors
QFile fixedFile(fwdFile.fileName());
const MNEForwardSolution fixedFwd = MNEForwardSolution(fixedFile, true, true).pick_regions({v1}).pick_channels(inverse.noise_cov->names);
const MatrixXd gain = whitener * fixedFwd.sol->data * 1e-9;
const MatrixXd measured = whitener * evoked.pick_channels(inverse.noise_cov->names).data.middleCols(170, 40); // 83-148 ms
const double alphaMax = (gain.transpose() * measured).rowwise().norm().maxCoeff();
const InvMxneResult mxne = InvMxne::compute(gain, measured, 0.5 * alphaMax, 1000, 1e-10);

Functions​

applyInverseEpochs(epochs, inverse, lambda2, method, tmin, tstep, pickNormal)​

QList< [InvSourceEstimate](/docs/api/inv/inv-source-estimate) > applyInverseEpochs(const QList< Eigen::MatrixXd > & epochs, const [MNEInverseOperator](/docs/api/mne/mne-inverse-operator) & inverse, float lambda2, const QString & method, float tmin, float tstep, bool pickNormal);

Apply inverse operator to each epoch in a list.

For each epoch (data matrix), applies the minimum norm inverse and returns a list of source estimates. This is the equivalent of MNE-Python's mne.minimum_norm.apply_inverse_epochs().

Parameters:

  • epochs : const QList< Eigen::MatrixXd > & List of epoch data matrices (n_channels x n_times each).

  • inverse : const MNEInverseOperator & Pre-computed inverse operator.

  • lambda2 : float Regularization parameter (1/SNR^2).

  • method : const QString & "MNE", "dSPM", or "sLORETA".

  • tmin : float Start time of each epoch (seconds).

  • tstep : float Time step (1/sfreq).

  • pickNormal : bool If true, keep only the normal component.

Returns:

applyInverseRaw(raw, inverse, lambda2, method, from, to, pickNormal)​

[InvSourceEstimate](/docs/api/inv/inv-source-estimate) applyInverseRaw(const [FiffRawData](/docs/api/fiff/fiff-raw-data) & raw, const [MNEInverseOperator](/docs/api/mne/mne-inverse-operator) & inverse, float lambda2, const QString & method, int from, int to, bool pickNormal);

Apply inverse operator to raw data.

Reads the requested range and applies the inverse operator with nave = 1. Equivalent of MNE-Python's mne.minimum_norm.apply_inverse_raw(), except that from and to are absolute sample numbers and the source estimate starts at from / sfreq (MNE-Python counts from the first sample).

Parameters:

  • raw : const FiffRawData & Raw data object.

  • inverse : const MNEInverseOperator & Pre-computed inverse operator.

  • lambda2 : float Regularization parameter (1/SNR^2).

  • method : const QString & "MNE", "dSPM", or "sLORETA".

  • from : int First sample to process (default: first_samp).

  • to : int Last sample to process (default: last_samp).

  • pickNormal : bool If true, keep only the normal component.

Returns:

applyForward(fwd, stc, info)​

[FiffEvoked](/docs/api/fiff/fiff-evoked) applyForward(const [MNEForwardSolution](/docs/api/mne/mne-forward-solution) & fwd, const [InvSourceEstimate](/docs/api/inv/inv-source-estimate) & stc, const [FiffInfo](/docs/api/fiff/fiff-info) & info);

Project a source estimate to the sensors, as mne.apply_forward.

A free-orientation forward is first converted to fixed orientation along the (patch-averaged) cortical normals. The source estimate rows are matched to forward columns by vertex number per hemisphere (stc.nVerticesLh splits lh and rh); a vertex the forward lacks is an error. A forward without source spaces is used column by column. The evoked carries the forward's channels taken from info.

Parameters:

  • fwd : const MNEForwardSolution & Forward solution; its channels must all be in info.

  • stc : const InvSourceEstimate & Source estimate with one row per source.

  • info : const FiffInfo & Measurement info supplying the channel descriptions.

Returns:

  • FiffEvoked — Simulated evoked data, empty on error.

estimateSnr(evoked, inverse)​

QPair< Eigen::VectorXd, Eigen::VectorXd > estimateSnr(const [FiffEvoked](/docs/api/fiff/fiff-evoked) & evoked, const [MNEInverseOperator](/docs/api/mne/mne-inverse-operator) & inverse);

Estimate the SNR of evoked data as a function of time.

Equivalent of MNE-Python's mne.minimum_norm.estimate_snr(): snr is the global field power of the whitened data, snrEst the largest regularization 1/sqrt(lambda2) whose prediction error passes a chi^2 test at p = 0.001 (0 where snr <= 1).

Parameters:

Returns:

  • QPair< Eigen::VectorXd, Eigen::VectorXd > — Pair of (snr, snrEst), one value per time point.

computeWhitener(noiseCov, rank)​

QPair< Eigen::MatrixXd, int > computeWhitener(const [FiffCov](/docs/api/fiff/fiff-cov) & noiseCov, int rank);

Compute whitening matrix from a noise covariance.

Returns a whitening matrix W such that W * data has identity covariance. Matches MNE-Python's mne.cov.compute_whitener().

Parameters:

  • noiseCov : const FiffCov & Noise covariance matrix.

  • rank : int Desired rank (0 = auto from eigenvalues).

Returns:

  • QPair< Eigen::MatrixXd, int > — Pair of (whitener matrix, effective rank).

computeSourcePsd(stc, sfreq, fmin, fmax, nFft)​

QPair< Eigen::MatrixXd, Eigen::VectorXd > computeSourcePsd(const [InvSourceEstimate](/docs/api/inv/inv-source-estimate) & stc, float sfreq, float fmin, float fmax, int nFft);

Compute PSD for a source estimate using Welch's method.

Takes a source estimate (n_sources x n_times) and computes the power spectral density at each source vertex. Equivalent to MNE-Python's mne.minimum_norm.compute_source_psd().

Parameters:

  • stc : const InvSourceEstimate & Source estimate.

  • sfreq : float Sampling frequency (Hz).

  • fmin : float Minimum frequency of interest (Hz).

  • fmax : float Maximum frequency of interest (Hz).

  • nFft : int FFT length (0 = use data length).

Returns:

  • QPair< Eigen::MatrixXd, Eigen::VectorXd > — Pair of (PSD matrix [n_sources x n_freqs], frequency vector).

computeSourceBandPower(stc, sfreq, bands)​

QMap< QString, Eigen::VectorXd > computeSourceBandPower(const [InvSourceEstimate](/docs/api/inv/inv-source-estimate) & stc, float sfreq, const QMap< QString, QPair< float, float > > & bands);

Compute band power for source estimate.

Integrates source PSD within specified frequency bands.

Parameters:

  • stc : const InvSourceEstimate & Source estimate.

  • sfreq : float Sampling frequency (Hz).

  • bands : const QMap< QString, QPair< float, float > > & Map of band name -> (fmin, fmax) pairs.

Returns:

  • QMap< QString, Eigen::VectorXd > — Map of band name -> power vector (n_sources).

Example​

Authors of this file​