Skip to main content

InvDipoleFitData

Namespace: INVLIB  ·  Library: Inverse Library

#include <inv/inv_dipole_fit_data.h>

class INVLIB::InvDipoleFitData

Dipole fit workspace holding sensor geometry, forward model, noise covariance, and projection data.

InvDipoleFitData aggregates everything needed to evaluate the dipole fitting objective function: coordinate transforms, channel lists, coil/ electrode definitions, forward-model function pointers (sphere or BEM), noise covariance, and SSP projection. The static factory setup_dipole_fit_data() reads all inputs from disk and returns a fully initialised instance.

Refactored from dipoleFitDataRec / fit_types.h (MNE-C).

src/examples/ex_inv_dipole_fit/main.cpp
// MEG channels and SSP projectors from the sample file, sphere at (0, 0, 40) mm, ad-hoc noise
// (5e-13 T/m gradiometers, 20 fT magnetometers).
Vector3f r0(0.0f, 0.0f, 0.04f);
std::unique_ptr<InvDipoleFitData> fitData(InvDipoleFitData::setup_dipole_fit_data(
    QString(), sampleAve, QString(), &r0, nullptr, false, QString(), QString(),
    5e-13f, 20e-15f, 0.2e-6f, 0.1f, 0.1f, 0.1f, false, {sampleAve}, true, false));
MatrixXf gain(fitData->nmeg, 3);
const bool fieldOk = InvDipoleFitData::compute_dipole_field(*fitData, truePos, false, gain) == 0; // projected, not whitened
VectorXf field = gain * trueMoment;

InvGuessData guesses(QString(), QString(), 0.0f, 0.02f, 0.015f, fitData.get(), 0.08f); // 15 mm grid in an 80 mm sphere
std::unique_ptr<InvDipoleForward> atTruth(InvDipoleFitData::dipole_forward_one(fitData.get(), truePos, nullptr));
InvEcd dipole;
VectorXf b = field; // fit_one projects and whitens in place
const bool fitted = InvDipoleFitData::fit_one(fitData.get(), &guesses, 0.0f, b, false, dipole);

Public Methods​

InvDipoleFitData()​

Default Constructor.

~InvDipoleFitData()​

Destructs the Dipole Fit Data Refactored: free_dipole_fit_data (dipole_fit_setup.c).

Static Methods​

setup_forward_model(d, comp_data, comp_coils)​

Set up the sphere-model and (optionally) BEM forward functions.

Initialises sphere_funcs, bem_funcs, and mag_dipole_funcs, applies CTF compensation if needed, and selects the active forward model.

Refactored: setup_forward_model (dipole_fit_setup.c)

Parameters:

Returns:

  • int — OK on success, FAIL on error.

ad_hoc_noise(meg, eeg, grad_std, mag_std, eeg_std)​

Create an ad-hoc diagonal noise-covariance matrix.

Builds a diagonal noise covariance from fixed standard deviations for gradiometers, magnetometers, and EEG channels.

Refactored: ad_hoc_noise (dipole_fit_setup.c)

Parameters:

  • meg : *FwdCoilSet ** MEG coil set (used to classify grad vs. mag channels).

  • eeg : *FwdCoilSet ** EEG electrode set.

  • grad_std : float Standard deviation for planar gradiometers (T/m).

  • mag_std : float Standard deviation for magnetometers (T).

  • eeg_std : float Standard deviation for EEG channels (V).

Returns:

  • std::unique_ptr< MNECovMatrix > — The noise-covariance matrix, or nullptr on error.

scale_noise_cov(f, nave)​

Scale the noise-covariance matrix for a given number of averages.

Re-decomposes the covariance after scaling by nave_old / nave_new.

Refactored: scale_noise_cov (dipole_fit_setup.c)

Parameters:

  • f : *InvDipoleFitData ** Dipole fit data whose noise member is scaled.

  • nave : int Number of averages in the current data.

Returns:

  • int — OK on success, FAIL on error.

scale_dipole_fit_noise_cov(f, nave)​

Scale dipole-fit noise covariance for a given number of averages.

Wrapper around scale_noise_cov() called from the dipole-fit pipeline.

Refactored: scale_dipole_fit_noise_cov (dipole_fit_setup.c)

Parameters:

  • f : *InvDipoleFitData ** Dipole fit data whose noise member is scaled.

  • nave : int Number of averages.

Returns:

  • int — OK on success, FAIL on error.

select_dipole_fit_noise_cov(f, meas, nave, sels)​

Select and weight the noise-covariance for the active channel set.

Channels present in the measurement data selection receive unit weight; omitted channels receive a reduced weight.

When meas is nullptr the function simply scales the noise covariance for nave = 1 (initial setup case).

Refactored: select_dipole_fit_noise_cov (dipole_fit_setup.c)

Parameters:

  • f : *InvDipoleFitData ** Dipole fit data whose noise_orig is used to build the weighted noise member.

  • meas : *MNEMeasData ** Measurement data with channel info (may be nullptr).

  • nave : int Number of averages override (< 0 to use meas->current->nave).

  • sels : *const int ** Per-channel selection flags (size >= meas->nchan, may be nullptr).

Returns:

  • int — OK on success, FAIL on error.

setup_dipole_fit_data(mriname, measname, bemname, r0, eeg_model, accurate_coils, badname, noisename, grad_std, mag_std, eeg_std, mag_reg, grad_reg, eeg_reg, diagnoise, projnames, include_meg, include_eeg)​

Master setup: read all inputs and build a ready-to-use fit workspace.

Reads coordinate transforms, channel info, BEM/sphere model, noise covariance, SSP projections, and compiles the forward model.

Refactored: setup_dipole_fit_data (dipole_fit_setup.c)

Parameters:

  • mriname : const QString & MRI-to-head transform file.

  • measname : const QString & Measurement file (provides MEG-to-head transform and channels).

  • bemname : const QString & BEM model file (empty string to use sphere model only).

  • r0 : *Eigen::Vector3f ** Sphere-model origin in head coordinates (may be nullptr).

  • eeg_model : *FwdEegSphereModel ** EEG sphere model definition (may be nullptr).

  • accurate_coils : int Use accurate coil definitions.

  • badname : const QString & Bad-channel list file (empty to skip).

  • noisename : const QString & Noise-covariance file (empty for ad-hoc noise).

  • grad_std : float Ad-hoc noise std for planar gradiometers (T/m).

  • mag_std : float Ad-hoc noise std for magnetometers (T).

  • eeg_std : float Ad-hoc noise std for EEG channels (V).

  • mag_reg : float Magnetometer noise-covariance regularization factor.

  • grad_reg : float Gradiometer noise-covariance regularization factor.

  • eeg_reg : float EEG noise-covariance regularization factor.

  • diagnoise : int Use only the diagonal of the noise covariance.

  • projnames : const QList< QString > & SSP projection file paths.

  • include_meg : int Include MEG channels in the fit.

  • include_eeg : int Include EEG channels in the fit.

Returns:

  • *InvDipoleFitData ** — Fully initialised fit data, or nullptr on error. Caller takes ownership.

fit_one(fit, guess, time, B, verbose, res)​

Fit a single dipole to the given data.

Refactored: fit_one (fit_dipoles.c)

Parameters:

  • fit : *InvDipoleFitData ** Precomputed fitting data.

  • guess : *InvGuessData ** The initial guesses.

  • time : float Time point (s).

  • B : Eigen::Ref< Eigen::VectorXf > The field to fit (modified in-place by projection and whitening).

  • verbose : int Verbose output flag.

  • res : InvEcd & The fitted dipole.

Returns:

  • bool — true on success, false on fitting failure.

compute_dipole_field(d, rd, whiten, fwd)​

Compute the forward field for a dipole at the given location.

Evaluates the MEG and/or EEG forward model at position rd and optionally applies noise whitening.

Refactored: compute_dipole_field (fit_dipoles.c)

Parameters:

  • d : InvDipoleFitData & Dipole fit workspace.

  • rd : const Eigen::Vector3f & Dipole position in head coordinates (m).

  • whiten : int If non-zero, whiten the result using the noise covariance.

  • fwd : Eigen::Ref< Eigen::MatrixXf > Forward field matrix (nchan x 3), filled on output.

Returns:

  • int — OK on success, FAIL on error.

Write the measured and the predicted field of a dipole, channel by channel.

A debugging aid: one line per fit channel with its name, the measured value at time and the value predicted by the dipole (MEG x 1e15, EEG x 1e6), both after projection.

Refactored: print_fields (fit_dipoles.c), which printed only CTF reference gradiometers.

Parameters:

  • rd : const Eigen::Vector3f & Dipole position in head coordinates (m).

  • Q : const Eigen::Vector3f & Dipole moment (A m).

  • time : float Time point (s).

  • integ : float Integration window (s).

  • fit : InvDipoleFitData & Dipole fit workspace.

  • data : const MNEMeasData & Measurement data read for the fit channels.

  • out : QTextStream & Stream the table is written to.

Returns:

  • bool — true on success, false if the time cannot be picked or the channels do not match.

dipole_forward_one(d, rd, old)​

Compute the forward solution for a single dipole position.

Returns a fully initialised InvDipoleForward with the forward field, its SVD, and noise-normalised goodness-of-fit limit. An existing object may be recycled via old.

Refactored: dipole_forward_one (fit_dipoles.c)

Parameters:

  • d : *InvDipoleFitData ** Dipole fit workspace.

  • rd : const Eigen::Vector3f & Dipole position in head coordinates (m).

  • old : std::unique_ptr< InvDipoleForward > Existing forward to recycle when its size matches (may be nullptr).

Returns:

  • std::unique_ptr< InvDipoleForward > — The populated forward object, or nullptr on error.

Example​

Used in examples​

ex_inv_dipole_fit​

Inverse library: equivalent current dipole fitting in a sphere model.

src/examples/ex_inv_dipole_fit/main.cpp, line 96
// MEG channels and SSP projectors from the sample file, sphere at (0, 0, 40) mm, ad-hoc noise
// (5e-13 T/m gradiometers, 20 fT magnetometers).
Vector3f r0(0.0f, 0.0f, 0.04f);
std::unique_ptr<InvDipoleFitData> fitData(InvDipoleFitData::setup_dipole_fit_data(
    QString(), sampleAve, QString(), &r0, nullptr, false, QString(), QString(),
    5e-13f, 20e-15f, 0.2e-6f, 0.1f, 0.1f, 0.1f, false, {sampleAve}, true, false));
MatrixXf gain(fitData->nmeg, 3);
const bool fieldOk = InvDipoleFitData::compute_dipole_field(*fitData, truePos, false, gain) == 0; // projected, not whitened
VectorXf field = gain * trueMoment;

Authors of this file​