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

#include <inv_dipole_fit_data.h>

Public Types
typedef QSharedPointer< InvDipoleFitData >	SPtr
typedef QSharedPointer< const InvDipoleFitData >	ConstSPtr

Public Member Functions
	InvDipoleFitData ()
virtual	~InvDipoleFitData ()

Static Public Member Functions
static int	setup_forward_model (InvDipoleFitData d, MNELIB::MNECTFCompDataSet comp_data, FWDLIB::FwdCoilSet *comp_coils)
	Set up the sphere-model and (optionally) BEM forward functions.
static std::unique_ptr< MNELIB::MNECovMatrix >	ad_hoc_noise (FWDLIB::FwdCoilSet meg, FWDLIB::FwdCoilSet eeg, float grad_std, float mag_std, float eeg_std)
	Create an ad-hoc diagonal noise-covariance matrix.
static int	scale_noise_cov (InvDipoleFitData *f, int nave)
	Scale the noise-covariance matrix for a given number of averages.
static int	scale_dipole_fit_noise_cov (InvDipoleFitData *f, int nave)
	Scale dipole-fit noise covariance for a given number of averages.
static int	select_dipole_fit_noise_cov (InvDipoleFitData f, MNELIB::MNEMeasData meas, int nave, const int *sels)
	Select and weight the noise-covariance for the active channel set.
static InvDipoleFitData *	setup_dipole_fit_data (const QString &mriname, const QString &measname, const QString &bemname, Eigen::Vector3f r0, FWDLIB::FwdEegSphereModel eeg_model, int accurate_coils, const QString &badname, const QString &noisename, float grad_std, float mag_std, float eeg_std, float mag_reg, float grad_reg, float eeg_reg, int diagnoise, const QList< QString > &projnames, int include_meg, int include_eeg)
	Master setup: read all inputs and build a ready-to-use fit workspace.
static bool	fit_one (InvDipoleFitData fit, InvGuessData guess, float time, Eigen::Ref< Eigen::VectorXf > B, int verbose, InvEcd &res)
	Fit a single dipole to the given data.
static int	compute_dipole_field (InvDipoleFitData &d, const Eigen::Vector3f &rd, int whiten, Eigen::Ref< Eigen::MatrixXf > fwd)
	Compute the forward field for a dipole at the given location.
static InvDipoleForward *	dipole_forward_one (InvDipoleFitData d, const Eigen::Vector3f &rd, InvDipoleForward old)
	Compute the forward solution for a single dipole position.

Public Attributes
std::unique_ptr< FIFFLIB::FiffCoordTrans >	mri_head_t
std::unique_ptr< FIFFLIB::FiffCoordTrans >	meg_head_t
int	coord_frame
QList< FIFFLIB::FiffChInfo >	chs
int	nmeg
int	neeg
QStringList	ch_names
std::unique_ptr< FIFFLIB::FiffSparseMatrix >	pick
std::unique_ptr< FWDLIB::FwdCoilSet >	meg_coils
std::unique_ptr< FWDLIB::FwdCoilSet >	eeg_els
Eigen::Vector3f	r0
QString	bemname
std::unique_ptr< FWDLIB::FwdEegSphereModel >	eeg_model
std::unique_ptr< FWDLIB::FwdBemModel >	bem_model
std::unique_ptr< dipoleFitFuncsRec >	sphere_funcs
std::unique_ptr< dipoleFitFuncsRec >	bem_funcs
dipoleFitFuncsRec *	funcs = nullptr
std::unique_ptr< dipoleFitFuncsRec >	mag_dipole_funcs
int	fixed_noise
std::unique_ptr< MNELIB::MNECovMatrix >	noise_orig
std::unique_ptr< MNELIB::MNECovMatrix >	noise
int	nave
std::unique_ptr< MNELIB::MNEProjOp >	proj
int	column_norm
int	fit_mag_dipoles
FitDipUserRec *	user

Detailed Description

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).

Definition at line 140 of file inv_dipole_fit_data.h.

Member Typedef Documentation

◆ ConstSPtr

typedef QSharedPointer<const InvDipoleFitData> INVLIB::InvDipoleFitData::ConstSPtr

Const shared pointer type for InvDipoleFitData.

Definition at line 144 of file inv_dipole_fit_data.h.

◆ SPtr

typedef QSharedPointer<InvDipoleFitData> INVLIB::InvDipoleFitData::SPtr

Shared pointer type for InvDipoleFitData.

Definition at line 143 of file inv_dipole_fit_data.h.

Constructor & Destructor Documentation

◆ InvDipoleFitData()

InvDipoleFitData::InvDipoleFitData ( )

explicit

Default Constructor

Definition at line 102 of file inv_dipole_fit_data.cpp.

◆ ~InvDipoleFitData()

InvDipoleFitData::~InvDipoleFitData ( )

virtual

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

Definition at line 118 of file inv_dipole_fit_data.cpp.

Member Function Documentation

◆ ad_hoc_noise()

std::unique_ptr< MNECovMatrix > InvDipoleFitData::ad_hoc_noise	(	FWDLIB::FwdCoilSet *	meg,
		FWDLIB::FwdCoilSet *	eeg,
		float	grad_std,
		float	mag_std,
		float	eeg_std )

static

Create an ad-hoc diagonal noise-covariance matrix.

Specify constant ad-hoc noise standard deviations for MEG and EEG channels.

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

Refactored: ad_hoc_noise (dipole_fit_setup.c)

Parameters

[in]	meg	MEG coil set (used to classify grad vs. mag channels).
[in]	eeg	EEG electrode set.
[in]	grad_std	Standard deviation for planar gradiometers (T/m).
[in]	mag_std	Standard deviation for magnetometers (T).
[in]	eeg_std	Standard deviation for EEG channels (V).

Returns: The noise-covariance matrix, or nullptr on error.

Definition at line 289 of file inv_dipole_fit_data.cpp.

◆ compute_dipole_field()

int InvDipoleFitData::compute_dipole_field	(	InvDipoleFitData &	d,
		const Eigen::Vector3f &	rd,
		int	whiten,
		Eigen::Ref< Eigen::MatrixXf >	fwd )

static

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

Compute the forward field for a dipole at position rd, applying projection and whitening.

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

Refactored: compute_dipole_field (fit_dipoles.c)

Parameters

[in]	d	Dipole fit workspace.
[in]	rd	Dipole position in head coordinates (m).
[in]	whiten	If non-zero, whiten the result using the noise covariance.
[in,out]	fwd	Forward field matrix (nchan x 3), filled on output.

Returns: OK on success, FAIL on error.

The output matrix fwd is nch x 3, with columns corresponding to X, Y, Z orientations.

Definition at line 1301 of file inv_dipole_fit_data.cpp.

◆ dipole_forward_one()

InvDipoleForward * InvDipoleFitData::dipole_forward_one	(	InvDipoleFitData *	d,
		const Eigen::Vector3f &	rd,
		InvDipoleForward *	old )

static

Compute the forward solution for a single dipole position.

Convenience function to compute the forward field of a single dipole.

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

[in]	d	Dipole fit workspace.
[in]	rd	Dipole position in head coordinates (m).
[in,out]	old	Existing forward to recycle (may be nullptr).

Returns: The populated forward object, or nullptr on error.

Definition at line 1003 of file inv_dipole_fit_data.cpp.

◆ fit_one()

bool InvDipoleFitData::fit_one	(	InvDipoleFitData *	fit,
		InvGuessData *	guess,
		float	time,
		Eigen::Ref< Eigen::VectorXf >	B,
		int	verbose,
		InvEcd &	res )

static

Fit a single dipole to the given data.

Fit a single dipole to the measured field at a given time point using simplex optimization.

Refactored: fit_one (fit_dipoles.c)

Parameters

[in]	fit	Precomputed fitting data.
[in]	guess	The initial guesses.
[in]	time	Time point (s).
[in,out]	B	The field to fit (modified in-place by projection and whitening).
[in]	verbose	Verbose output flag.
[out]	res	The fitted dipole.

Returns: true on success, false on fitting failure.

Parameters

[in]	fit	Precomputed fitting data (forward model, noise, projection).
[in]	guess	Initial guess positions for the dipole search.
[in]	time	Time point being fitted (seconds).
[in,out]	B	Measured field vector (whitened in-place).
[in]	verbose	If non-zero, print intermediate results.
[out]	res	The fitted dipole result.

Returns: true if fit succeeded, false on failure.

Definition at line 1172 of file inv_dipole_fit_data.cpp.

◆ scale_dipole_fit_noise_cov()

int InvDipoleFitData::scale_dipole_fit_noise_cov	(	InvDipoleFitData *	f,
		int	nave )

static

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

[in,out]	f	Dipole fit data whose noise member is scaled.
[in]	nave	Number of averages.

Returns: OK on success, FAIL on error.

Definition at line 374 of file inv_dipole_fit_data.cpp.

◆ scale_noise_cov()

int InvDipoleFitData::scale_noise_cov	(	InvDipoleFitData *	f,
		int	nave )

static

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

[in,out]	f	Dipole fit data whose noise member is scaled.
[in]	nave	Number of averages in the current data.

Returns: OK on success, FAIL on error.

Definition at line 337 of file inv_dipole_fit_data.cpp.

◆ select_dipole_fit_noise_cov()

int InvDipoleFitData::select_dipole_fit_noise_cov	(	InvDipoleFitData *	f,
		MNELIB::MNEMeasData *	meas,
		int	nave_in,
		const int *	sels )

static

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

Select channels and scale the noise covariance for the dipole fit.

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

[in,out]	f	Dipole fit data whose noise_orig is used to build the weighted noise member.
[in]	meas	Measurement data with channel info (may be nullptr).
[in]	nave	Number of averages override (< 0 to use meas->current->nave).
[in]	sels	Per-channel selection flags (size >= meas->nchan, may be nullptr).

Returns: OK on success, FAIL on error.

When meas is non-null, channels not selected in sels receive an increased weight (nonsel_w) in the noise covariance, effectively down-weighting their contribution during fitting.

Refactored: select_dipole_fit_noise_cov (dipole_fit_setup.c, SVN MNE)

Definition at line 430 of file inv_dipole_fit_data.cpp.

◆ setup_dipole_fit_data()

InvDipoleFitData * InvDipoleFitData::setup_dipole_fit_data	(	const QString &	mriname,
		const QString &	measname,
		const QString &	bemname,
		Eigen::Vector3f *	r0,
		FWDLIB::FwdEegSphereModel *	eeg_model,
		int	accurate_coils,
		const QString &	badname,
		const QString &	noisename,
		float	grad_std,
		float	mag_std,
		float	eeg_std,
		float	mag_reg,
		float	grad_reg,
		float	eeg_reg,
		int	diagnoise,
		const QList< QString > &	projnames,
		int	include_meg,
		int	include_eeg )

static

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

Set up all resources needed for dipole fitting: channels, covariance, projection, and forward model.

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

[in]	mriname	MRI-to-head transform file.
[in]	measname	Measurement file (provides MEG-to-head transform and channels).
[in]	bemname	BEM model file (empty string to use sphere model only).
[in]	r0	Sphere-model origin in head coordinates (may be nullptr).
[in]	eeg_model	EEG sphere model definition (may be nullptr).
[in]	accurate_coils	Use accurate coil definitions.
[in]	badname	Bad-channel list file (empty to skip).
[in]	noisename	Noise-covariance file (empty for ad-hoc noise).
[in]	grad_std	Ad-hoc noise std for planar gradiometers (T/m).
[in]	mag_std	Ad-hoc noise std for magnetometers (T).
[in]	eeg_std	Ad-hoc noise std for EEG channels (V).
[in]	mag_reg	Magnetometer noise-covariance regularization factor.
[in]	grad_reg	Gradiometer noise-covariance regularization factor.
[in]	eeg_reg	EEG noise-covariance regularization factor.
[in]	diagnoise	Use only the diagonal of the noise covariance.
[in]	projnames	SSP projection file paths.
[in]	include_meg	Include MEG channels in the fit.
[in]	include_eeg	Include EEG channels in the fit.

Returns: Fully initialised fit data, or nullptr on error. Caller takes ownership.

Definition at line 522 of file inv_dipole_fit_data.cpp.

◆ setup_forward_model()

int InvDipoleFitData::setup_forward_model	(	InvDipoleFitData *	d,
		MNELIB::MNECTFCompDataSet *	comp_data,
		FWDLIB::FwdCoilSet *	comp_coils )

static

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

Set up forward model including BEM and sphere models, coil definitions, and compensation.

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

[in,out]	d	Dipole fit data to populate.
[in]	comp_data	CTF compensation data (may be nullptr).
[in]	comp_coils	Compensation coil set (may be nullptr).

Returns: OK on success, FAIL on error.

Definition at line 128 of file inv_dipole_fit_data.cpp.

Member Data Documentation

◆ bem_funcs

std::unique_ptr<dipoleFitFuncsRec> INVLIB::InvDipoleFitData::bem_funcs

These are the BEM forward functions.

Definition at line 377 of file inv_dipole_fit_data.h.

◆ bem_model

std::unique_ptr<FWDLIB::FwdBemModel> INVLIB::InvDipoleFitData::bem_model

BEM model definition.

Definition at line 374 of file inv_dipole_fit_data.h.

◆ bemname

QString INVLIB::InvDipoleFitData::bemname

Using a BEM?.

Definition at line 371 of file inv_dipole_fit_data.h.

◆ ch_names

QStringList INVLIB::InvDipoleFitData::ch_names

List of all channel names.

Definition at line 366 of file inv_dipole_fit_data.h.

◆ chs

QList<FIFFLIB::FiffChInfo> INVLIB::InvDipoleFitData::chs

Channels.

Definition at line 363 of file inv_dipole_fit_data.h.

◆ column_norm

int INVLIB::InvDipoleFitData::column_norm

What kind of column normalization to apply to the forward solution.

Definition at line 386 of file inv_dipole_fit_data.h.

◆ coord_frame

int INVLIB::InvDipoleFitData::coord_frame

Common coordinate frame.

Definition at line 362 of file inv_dipole_fit_data.h.

◆ eeg_els

std::unique_ptr<FWDLIB::FwdCoilSet> INVLIB::InvDipoleFitData::eeg_els

EEG electrode definitions.

Definition at line 369 of file inv_dipole_fit_data.h.

◆ eeg_model

std::unique_ptr<FWDLIB::FwdEegSphereModel> INVLIB::InvDipoleFitData::eeg_model

EEG sphere model definition.

Definition at line 373 of file inv_dipole_fit_data.h.

◆ fit_mag_dipoles

int INVLIB::InvDipoleFitData::fit_mag_dipoles

Fit magnetic dipoles?.

Definition at line 387 of file inv_dipole_fit_data.h.

◆ fixed_noise

int INVLIB::InvDipoleFitData::fixed_noise

Were fixed noise values used rather than a noise-covariance matrix read from a file.

Definition at line 381 of file inv_dipole_fit_data.h.

◆ funcs

dipoleFitFuncsRec* INVLIB::InvDipoleFitData::funcs = nullptr

Non-owning alias — points to one of the two above.

Definition at line 378 of file inv_dipole_fit_data.h.

◆ mag_dipole_funcs

std::unique_ptr<dipoleFitFuncsRec> INVLIB::InvDipoleFitData::mag_dipole_funcs

Functions to fit a magnetic dipole.

Definition at line 379 of file inv_dipole_fit_data.h.

◆ meg_coils

std::unique_ptr<FWDLIB::FwdCoilSet> INVLIB::InvDipoleFitData::meg_coils

MEG coil definitions.

Definition at line 368 of file inv_dipole_fit_data.h.

◆ meg_head_t

std::unique_ptr<FIFFLIB::FiffCoordTrans> INVLIB::InvDipoleFitData::meg_head_t

MEG <-> head coordinate transformation.

Definition at line 361 of file inv_dipole_fit_data.h.

◆ mri_head_t

std::unique_ptr<FIFFLIB::FiffCoordTrans> INVLIB::InvDipoleFitData::mri_head_t

MRI <-> head coordinate transformation.

Definition at line 360 of file inv_dipole_fit_data.h.

◆ nave

int INVLIB::InvDipoleFitData::nave

How many averages does this correspond to?.

Definition at line 384 of file inv_dipole_fit_data.h.

◆ neeg

int INVLIB::InvDipoleFitData::neeg

How many EEG.

Definition at line 365 of file inv_dipole_fit_data.h.

◆ nmeg

int INVLIB::InvDipoleFitData::nmeg

How many MEG.

Definition at line 364 of file inv_dipole_fit_data.h.

◆ noise

std::unique_ptr<MNELIB::MNECovMatrix> INVLIB::InvDipoleFitData::noise

Noise covariance matrix (weighted to take the selection into account).

Definition at line 383 of file inv_dipole_fit_data.h.

◆ noise_orig

std::unique_ptr<MNELIB::MNECovMatrix> INVLIB::InvDipoleFitData::noise_orig

Noise covariance matrix (original, currently unused).

Definition at line 382 of file inv_dipole_fit_data.h.

◆ pick

std::unique_ptr<FIFFLIB::FiffSparseMatrix> INVLIB::InvDipoleFitData::pick

Matrix to pick data from the full data set which may contain channels we are not interested in (currently unused).

Definition at line 367 of file inv_dipole_fit_data.h.

◆ proj

std::unique_ptr<MNELIB::MNEProjOp> INVLIB::InvDipoleFitData::proj

The projection operator to use.

Definition at line 385 of file inv_dipole_fit_data.h.

◆ r0

Eigen::Vector3f INVLIB::InvDipoleFitData::r0

Sphere model origin.

Definition at line 370 of file inv_dipole_fit_data.h.

◆ sphere_funcs

std::unique_ptr<dipoleFitFuncsRec> INVLIB::InvDipoleFitData::sphere_funcs

These are the sphere model forward functions.

Definition at line 376 of file inv_dipole_fit_data.h.

◆ user

FitDipUserRec* INVLIB::InvDipoleFitData::user

Non-owning pointer to dipole fit workspace (set during fit_one).

Definition at line 388 of file inv_dipole_fit_data.h.

The documentation for this class was generated from the following files:

src/libraries/inv/dipole_fit/inv_dipole_fit_data.h
src/libraries/inv/dipole_fit/inv_dipole_fit_data.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ ConstSPtr

◆ SPtr

Constructor & Destructor Documentation

◆ InvDipoleFitData()

◆ ~InvDipoleFitData()

Member Function Documentation

◆ ad_hoc_noise()

◆ compute_dipole_field()

◆ dipole_forward_one()

◆ fit_one()

◆ scale_dipole_fit_noise_cov()

◆ scale_noise_cov()

◆ select_dipole_fit_noise_cov()

◆ setup_dipole_fit_data()

◆ setup_forward_model()

Member Data Documentation

◆ bem_funcs

◆ bem_model

◆ bemname

◆ ch_names

◆ chs

◆ column_norm

◆ coord_frame

◆ eeg_els

◆ eeg_model

◆ fit_mag_dipoles

◆ fixed_noise

◆ funcs

◆ mag_dipole_funcs

◆ meg_coils

◆ meg_head_t

◆ mri_head_t

◆ nave

◆ neeg

◆ nmeg

◆ noise

◆ noise_orig

◆ pick

◆ proj

◆ r0

◆ sphere_funcs

◆ user