Skip to main content

InvDICS

Namespace: INVLIB  ·  Library: Inverse Library

Python equivalent

mne.beamformer.make_dics / apply_dics in MNE-Python.

#include <inv/inv_dics.h>

class INVLIB::InvDICS

Dynamic Imaging of Coherent Sources (DICS) beamformer for frequency-domain source localization using cross-spectral density (CSD) matrices.

Typical workflow:

DICS beamformer (frequency-domain).

src/examples/ex_inv_beamformer/main.cpp
// A single real cross-spectral density at 10 Hz equal to the data covariance gives the LCMV power.
const VectorXd frequencies = VectorXd::Constant(1, 10.0);
const InvBeamformer dics = InvDICS::makeDICS(info, fwd, {dataCov.data}, frequencies, 0.05, true, noiseCov,
                                             BeamformerPickOri::MaxPower, BeamformerWeightNorm::UnitNoiseGain);
const VectorXd dicsPower = InvDICS::applyDICSCsd({dataCov.data}, frequencies, dics).data.col(0);

Static Methods​

makeDICS(info, forward, csdMatrices, frequencies, reg, realFilter, noiseCov, pickOri, weightNorm, reduceRank, invMethod)​

Compute DICS beamformer spatial filters for one or more frequencies.

Parameters:

  • info : const FiffInfo & Measurement info.

  • forward : const MNEForwardSolution & Forward solution containing the leadfield.

  • csdMatrices : const std::vector< Eigen::MatrixXd > & Cross-spectral density matrices, one per frequency bin. Each is (n_channels, n_channels), may be complex.

  • frequencies : const Eigen::VectorXd & Center frequency (Hz) for each CSD matrix.

  • reg : double Regularization parameter (default 0.05).

  • realFilter : bool If true, take real part of CSD before computing filter (default true).

  • noiseCov : const FiffCov & Noise covariance for whitening. If empty, identity whitening.

  • pickOri : BeamformerPickOri Orientation selection mode.

  • weightNorm : BeamformerWeightNorm Weight normalization strategy.

  • reduceRank : bool Reduce leadfield rank by 1.

  • invMethod : BeamformerInversion Denominator inversion method.

Returns:

  • InvBeamformer — Beamformer with one filter weight matrix per frequency.

applyDICSCsd(csdMatrices, frequencies, filters)​

Apply DICS beamformer to CSD matrices to estimate source power per frequency.

power_i(f) = trace(W_f_i @ CSD_f @ W_f_i^T)

Parameters:

  • csdMatrices : const std::vector< Eigen::MatrixXd > & CSD matrices (one per frequency).

  • frequencies : const Eigen::VectorXd & Center frequencies (Hz).

  • filters : const InvBeamformer & Pre-computed DICS beamformer from makeDICS().

Returns:

  • InvSourceEstimate — Source estimate where data has shape (n_sources, n_freqs) with power values.

applyDICS(data, tmin, tstep, filters, freqIdx)​

Apply DICS beamformer to time-domain data at a single frequency.

This is an approximate application — for accurate frequency-domain source estimation, use applyDICSCsd() with CSD matrices.

Parameters:

  • data : const Eigen::MatrixXd & Data matrix (n_channels, n_times).

  • tmin : float Start time (s).

  • tstep : float Time step (s).

  • filters : const InvBeamformer & Pre-computed DICS beamformer (must have exactly 1 frequency).

  • freqIdx : int Index of the frequency filter to use (default 0).

Returns:

applyDICSEpochs(epochs, tmin, tstep, filters, freqIdx)​

Apply DICS beamformer to each epoch in a list.

Parameters:

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

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

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

  • filters : const InvBeamformer & Pre-computed DICS beamformer from makeDICS().

  • freqIdx : int Index of the frequency filter to use (default 0).

Returns:

Example​

Used in examples​

ex_inv_beamformer​

Inverse library: LCMV and DICS beamformers and the RAP-MUSIC family of dipole scanners.

src/examples/ex_inv_beamformer/main.cpp, line 140
// A single real cross-spectral density at 10 Hz equal to the data covariance gives the LCMV power.
const VectorXd frequencies = VectorXd::Constant(1, 10.0);
const InvBeamformer dics = InvDICS::makeDICS(info, fwd, {dataCov.data}, frequencies, 0.05, true, noiseCov,
                                             BeamformerPickOri::MaxPower, BeamformerWeightNorm::UnitNoiseGain);
const VectorXd dicsPower = InvDICS::applyDICSCsd({dataCov.data}, frequencies, dics).data.col(0);
// mne.beamformer.make_dics(..., real_filter=True, depth=None) + apply_dics_csd: sum 117.705, source 10 16.5306
ok &= expect(dics.isValid() && near(dicsPower.sum(), 117.70495401992135, 1e-5) && near(dicsPower(10), 16.530644991359814, 1e-5),
             "InvDICS: DICS power for a 10 Hz CSD matches mne.beamformer.apply_dics_csd");

Authors of this file​