Covariance matrix storage. More...

#include <mne_cov_matrix.h>

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

Public Member Functions
	MNECovMatrix (int p_kind, int p_ncov, const QStringList &p_names, const Eigen::VectorXd &p_cov, const Eigen::VectorXd &p_cov_diag, FIFFLIB::FiffSparseMatrix *p_cov_sparse)
	~MNECovMatrix ()
std::unique_ptr< MNECovMatrix >	dup () const
int	is_diag () const
int	add_inv ()
int	condition (float rank_threshold, int use_rank)
int	decompose_eigen_small (float p_small, int use_rank)
int	decompose_eigen ()
int	classify_channels (const QList< FIFFLIB::FiffChInfo > &chs, int nchan)
int	whiten_vector (Eigen::Ref< Eigen::VectorXf > data, Eigen::Ref< Eigen::VectorXf > whitened_data, int nchan) const
void	regularize (const Eigen::Vector3f &regs)
void	revert_to_diag ()
std::unique_ptr< MNECovMatrix >	pick_chs_omit (const QStringList &new_names, int new_ncov, int omit_meg_eeg, const QList< FIFFLIB::FiffChInfo > &chs) const

Static Public Member Functions
static std::unique_ptr< MNECovMatrix >	create_dense (int kind, int ncov, const QStringList &names, const Eigen::VectorXd &cov)
static std::unique_ptr< MNECovMatrix >	create_diag (int kind, int ncov, const QStringList &names, const Eigen::VectorXd &cov_diag)
static std::unique_ptr< MNECovMatrix >	create_sparse (int kind, int ncov, const QStringList &names, FIFFLIB::FiffSparseMatrix *cov_sparse)
static std::unique_ptr< MNECovMatrix >	create (int kind, int ncov, const QStringList &names, const Eigen::VectorXd &cov, const Eigen::VectorXd &cov_diag)
static std::unique_ptr< MNECovMatrix >	read (const QString &name, int kind)
static int	lt_packed_index (int j, int k)

Public Attributes
int	kind
int	ncov
int	nfree
int	nproj
int	nzero
QStringList	names
Eigen::VectorXd	cov
Eigen::VectorXd	cov_diag
std::unique_ptr< FIFFLIB::FiffSparseMatrix >	cov_sparse
Eigen::VectorXd	lambda
Eigen::VectorXd	inv_lambda
Eigen::Matrix< float, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor >	eigen
std::unique_ptr< MNEProjOp >	proj
std::unique_ptr< MNESssData >	sss
Eigen::VectorXi	ch_class
QStringList	bads
int	nbad

Detailed Description

Covariance matrix storage.

Stores a noise or source covariance matrix in dense (packed lower-triangle), diagonal, or sparse form together with its eigendecomposition and associated metadata (projection operator, SSS info, channel classification, bad channels).

Definition at line 105 of file mne_cov_matrix.h.

Member Typedef Documentation

◆ ConstSPtr

typedef QSharedPointer<const MNECovMatrix> MNELIB::MNECovMatrix::ConstSPtr

Const shared pointer type for MNECovMatrix.

Definition at line 109 of file mne_cov_matrix.h.

◆ SPtr

typedef QSharedPointer<MNECovMatrix> MNELIB::MNECovMatrix::SPtr

Shared pointer type for MNECovMatrix.

Definition at line 108 of file mne_cov_matrix.h.

Constructor & Destructor Documentation

◆ MNECovMatrix()

MNECovMatrix::MNECovMatrix	(	int	p_kind,
		int	p_ncov,
		const QStringList &	p_names,
		const Eigen::VectorXd &	p_cov,
		const Eigen::VectorXd &	p_cov_diag,
		FIFFLIB::FiffSparseMatrix *	p_cov_sparse )

Construct a covariance matrix.

Parameters

[in]	p_kind	Covariance kind (sensor or source).
[in]	p_ncov	Dimension (number of channels).
[in]	p_names	Channel names.
[in]	p_cov	Packed lower-triangle data (may be empty).
[in]	p_cov_diag	Diagonal data (may be empty).
[in]	p_cov_sparse	Sparse covariance data (may be nullptr).

Definition at line 124 of file mne_cov_matrix.cpp.

◆ ~MNECovMatrix()

MNECovMatrix::~MNECovMatrix ( )

Destructor.

Definition at line 147 of file mne_cov_matrix.cpp.

Member Function Documentation

◆ add_inv()

int MNECovMatrix::add_inv ( )

Compute the inverse square-root of eigenvalues (or diagonal elements) for whitening, storing the result in inv_lambda.

Returns: OK on success, FAIL if neither diagonal nor decomposed.

Definition at line 393 of file mne_cov_matrix.cpp.

◆ classify_channels()

int MNECovMatrix::classify_channels	(	const QList< FIFFLIB::FiffChInfo > &	chs,
		int	nchan )

Assign channel-type classifications (MEG mag, MEG grad, EEG) to channels in this covariance matrix, based on channel information.

Parameters

[in]	chs	Channel information list.
[in]	nchan	Number of channels in chs.

Returns: OK on success, FAIL if channel information is not available.

Definition at line 625 of file mne_cov_matrix.cpp.

◆ condition()

int MNECovMatrix::condition	(	float	rank_threshold,
		int	use_rank )

Condition the covariance matrix by eigendecomposition with per-channel-type scaling, zeroing sub-threshold eigenvalues, and reconstructing.

Parameters

[in]	rank_threshold	Eigenvalue threshold ratio for rank estimation.
[in]	use_rank	If positive, override the automatic rank estimate.

Returns: The estimated rank, or FAIL on error.

Definition at line 417 of file mne_cov_matrix.cpp.

◆ create()

std::unique_ptr< MNECovMatrix > MNELIB::MNECovMatrix::create	(	int	kind,
		int	ncov,
		const QStringList &	names,
		const Eigen::VectorXd &	cov,
		const Eigen::VectorXd &	cov_diag )

inlinestatic

Create a covariance matrix from either dense or diagonal data.

Parameters

[in]	kind	Covariance kind (sensor or source).
[in]	ncov	Dimension (number of channels).
[in]	names	Channel names.
[in]	cov	Packed lower-triangle data (may be empty).
[in]	cov_diag	Diagonal data (may be empty).

Returns: A new covariance matrix.

Definition at line 208 of file mne_cov_matrix.h.

◆ create_dense()

std::unique_ptr< MNECovMatrix > MNELIB::MNECovMatrix::create_dense	(	int	kind,
		int	ncov,
		const QStringList &	names,
		const Eigen::VectorXd &	cov )

inlinestatic

Create a dense (full lower-triangle packed) covariance matrix.

Parameters

[in]	kind	Covariance kind (sensor or source).
[in]	ncov	Dimension (number of channels).
[in]	names	Channel names.
[in]	cov	Packed lower-triangle data (length ncov*(ncov+1)/2). Ownership transferred.

Returns: A new covariance matrix.

Definition at line 150 of file mne_cov_matrix.h.

◆ create_diag()

std::unique_ptr< MNECovMatrix > MNELIB::MNECovMatrix::create_diag	(	int	kind,
		int	ncov,
		const QStringList &	names,
		const Eigen::VectorXd &	cov_diag )

inlinestatic

Create a diagonal covariance matrix.

Parameters

[in]	kind	Covariance kind (sensor or source).
[in]	ncov	Dimension (number of channels).
[in]	names	Channel names.
[in]	cov_diag	Diagonal data (ncov elements).

Returns: A new covariance matrix.

Definition at line 169 of file mne_cov_matrix.h.

◆ create_sparse()

std::unique_ptr< MNECovMatrix > MNELIB::MNECovMatrix::create_sparse	(	int	kind,
		int	ncov,
		const QStringList &	names,
		FIFFLIB::FiffSparseMatrix *	cov_sparse )

inlinestatic

Create a sparse covariance matrix.

Parameters

[in]	kind	Covariance kind (sensor or source).
[in]	ncov	Dimension (number of channels).
[in]	names	Channel names.
[in]	cov_sparse	Sparse covariance data (note: data are floats).

Returns: A new covariance matrix.

Definition at line 188 of file mne_cov_matrix.h.

◆ decompose_eigen()

int MNECovMatrix::decompose_eigen ( )

Convenience wrapper for decompose_eigen_small() with default threshold and no rank override.

Returns: OK on success, FAIL on error.

Definition at line 606 of file mne_cov_matrix.cpp.

◆ decompose_eigen_small()

int MNECovMatrix::decompose_eigen_small	(	float	p_small,
		int	use_rank )

Perform eigenvalue decomposition of the covariance matrix, zero sub-threshold eigenvalues, classify eigenvectors by channel type, and compute inverse square-roots for whitening.

Parameters

[in]	p_small	Eigenvalue threshold (negative uses default).
[in]	use_rank	If positive, override automatic rank estimate.

Returns: OK on success, FAIL on error.

Definition at line 537 of file mne_cov_matrix.cpp.

◆ dup()

std::unique_ptr< MNECovMatrix > MNECovMatrix::dup ( ) const

Create a deep copy of this covariance matrix including data, channel classes, bad channel list, projection, and SSS info.

Returns: A newly allocated copy.

Definition at line 364 of file mne_cov_matrix.cpp.

◆ is_diag()

int MNECovMatrix::is_diag ( ) const

Check whether this covariance matrix is stored in diagonal form.

Returns: Non-zero if diagonal, zero if full or sparse.

Definition at line 386 of file mne_cov_matrix.cpp.

◆ lt_packed_index()

int MNECovMatrix::lt_packed_index	(	int	j,
		int	k )

static

Compute the linear index into a symmetric lower-triangular packed storage array for element (j, k).

Parameters

[in]	j	Row index.
[in]	k	Column index.

Returns: The packed storage index.

Definition at line 614 of file mne_cov_matrix.cpp.

◆ pick_chs_omit()

std::unique_ptr< MNECovMatrix > MNECovMatrix::pick_chs_omit	(	const QStringList &	new_names,
		int	new_ncov,
		int	omit_meg_eeg,
		const QList< FIFFLIB::FiffChInfo > &	chs ) const

Pick designated channels from this covariance matrix, optionally omitting MEG-EEG cross-correlations.

Parameters

[in]	new_names	Names of channels to pick.
[in]	new_ncov	Number of channels to pick.
[in]	omit_meg_eeg	If non-zero, zero out MEG-EEG cross entries.
[in]	chs	Channel information list (for MEG/EEG classification).

Returns: A new covariance matrix with only the selected channels, or nullptr on error.

Definition at line 743 of file mne_cov_matrix.cpp.

◆ read()

std::unique_ptr< MNECovMatrix > MNECovMatrix::read	(	const QString &	name,
		int	kind )

static

Read a covariance matrix of the specified kind from a FIFF file.

Parameters

[in]	name	Path to the FIFF file.
[in]	kind	Covariance kind (e.g. FIFFV_MNE_SENSOR_COV).

Returns: The covariance matrix, or nullptr on failure.

Definition at line 153 of file mne_cov_matrix.cpp.

◆ regularize()

void MNECovMatrix::regularize ( const Eigen::Vector3f & regs )

Regularize different channel types of the covariance matrix by adding a fraction of the average diagonal value for each channel class.

Parameters

[in] regs Regularization fractions for [MEG_MAG, MEG_GRAD, EEG].

Definition at line 682 of file mne_cov_matrix.cpp.

◆ revert_to_diag()

void MNECovMatrix::revert_to_diag ( )

Revert a full (lower-triangle packed) covariance matrix to its diagonal elements, discarding off-diagonal data and eigendecomposition.

Definition at line 723 of file mne_cov_matrix.cpp.

◆ whiten_vector()

int MNECovMatrix::whiten_vector	(	Eigen::Ref< Eigen::VectorXf >	data,
		Eigen::Ref< Eigen::VectorXf >	whitened_data,
		int	nchan ) const

Apply whitening to a data vector using the inverse square-root eigenvalues stored in this covariance matrix.

Parameters

[in]	data	Input data vector.
[out]	whitened_data	Whitened output vector (may alias data for in-place).
[in]	nchan	Number of channels.

Returns: OK on success, FAIL if dimensions are incompatible.

Definition at line 657 of file mne_cov_matrix.cpp.

Member Data Documentation

◆ bads

QStringList MNELIB::MNECovMatrix::bads

Channel names designated bad during computation.

Definition at line 364 of file mne_cov_matrix.h.

◆ ch_class

Eigen::VectorXi MNELIB::MNECovMatrix::ch_class

Per-channel type classification for regularization (MEG grad, MEG mag, EEG).

Definition at line 363 of file mne_cov_matrix.h.

◆ cov

Eigen::VectorXd MNELIB::MNECovMatrix::cov

Packed lower-triangle covariance data (ncov*(ncov+1)/2 elements).

Definition at line 355 of file mne_cov_matrix.h.

◆ cov_diag

Eigen::VectorXd MNELIB::MNECovMatrix::cov_diag

Diagonal covariance data (ncov elements).

Definition at line 356 of file mne_cov_matrix.h.

◆ cov_sparse

std::unique_ptr<FIFFLIB::FiffSparseMatrix> MNELIB::MNECovMatrix::cov_sparse

Sparse covariance matrix (note: data are floats).

Definition at line 357 of file mne_cov_matrix.h.

◆ eigen

Eigen::Matrix<float, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor> MNELIB::MNECovMatrix::eigen

Eigenvectors of the covariance matrix (nzero columns removed).

Definition at line 360 of file mne_cov_matrix.h.

◆ inv_lambda

Eigen::VectorXd MNELIB::MNECovMatrix::inv_lambda

Inverse square-roots of eigenvalues (for whitening).

Definition at line 359 of file mne_cov_matrix.h.

◆ kind

int MNELIB::MNECovMatrix::kind

Covariance kind: sensor or source.

Definition at line 349 of file mne_cov_matrix.h.

◆ lambda

Eigen::VectorXd MNELIB::MNECovMatrix::lambda

Eigenvalues of the covariance matrix.

Definition at line 358 of file mne_cov_matrix.h.

◆ names

QStringList MNELIB::MNECovMatrix::names

Channel names (optional).

Definition at line 354 of file mne_cov_matrix.h.

◆ nbad

int MNELIB::MNECovMatrix::nbad

Number of bad channels.

Definition at line 365 of file mne_cov_matrix.h.

◆ ncov

int MNELIB::MNECovMatrix::ncov

Dimension (number of channels).

Definition at line 350 of file mne_cov_matrix.h.

◆ nfree

int MNELIB::MNECovMatrix::nfree

Number of degrees of freedom used in estimation.

Definition at line 351 of file mne_cov_matrix.h.

◆ nproj

int MNELIB::MNECovMatrix::nproj

Number of dimensions projected out.

Definition at line 352 of file mne_cov_matrix.h.

◆ nzero

int MNELIB::MNECovMatrix::nzero

Number of zero or small eigenvalues.

Definition at line 353 of file mne_cov_matrix.h.

◆ proj

std::unique_ptr<MNEProjOp> MNELIB::MNECovMatrix::proj

The projection operator active when this matrix was computed.

Definition at line 361 of file mne_cov_matrix.h.

◆ sss

std::unique_ptr<MNESssData> MNELIB::MNECovMatrix::sss

SSS data from the associated raw data file.

Definition at line 362 of file mne_cov_matrix.h.

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

src/libraries/mne/mne_cov_matrix.h
src/libraries/mne/mne_cov_matrix.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ ConstSPtr

◆ SPtr

Constructor & Destructor Documentation

◆ MNECovMatrix()

◆ ~MNECovMatrix()

Member Function Documentation

◆ add_inv()

◆ classify_channels()

◆ condition()

◆ create()

◆ create_dense()

◆ create_diag()

◆ create_sparse()

◆ decompose_eigen()

◆ decompose_eigen_small()

◆ dup()

◆ is_diag()

◆ lt_packed_index()

◆ pick_chs_omit()

◆ read()

◆ regularize()

◆ revert_to_diag()

◆ whiten_vector()

Member Data Documentation

◆ bads

◆ ch_class

◆ cov

◆ cov_diag

◆ cov_sparse

◆ eigen

◆ inv_lambda

◆ kind

◆ lambda

◆ names

◆ nbad

◆ ncov

◆ nfree

◆ nproj

◆ nzero

◆ proj

◆ sss