Skip to main content

MNECovMatrix

Namespace: MNELIB  ·  Library: MNE Library

#include <mne/mne_cov_matrix.h>

class MNELIB::MNECovMatrix

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

src/examples/ex_mne_api/main.cpp
// Whiten one time point of the evoked response with the projected noise covariance
QFile aveFile(data + "/MEG/sample/sample_audvis-ave.fif");
FiffEvoked ave(aveFile, 0, QPair<float, float>(-1.0f, -1.0f), false);
QStringList megNames; // the 305 good MEG channels
for (const QString& name : ave.info.ch_names) {
    if (name.startsWith("MEG") && !ave.info.bads.contains(name)) {
        megNames << name;
    }
}
ave = ave.pick_channels(megNames);
const int nMeg = static_cast<int>(megNames.size());
std::unique_ptr<MNEProjOp> aveProj;
MNEProjOp::makeProjection({aveFile.fileName()}, ave.info.chs, nMeg, aveProj);
aveProj->assign_channels(megNames, nMeg);
aveProj->make_proj();
VectorXf x = ave.data.col(200).cast<float>(); // t = 133 ms
aveProj->project_vector(x, true);

auto noise = MNECovMatrix::read(data + "/MEG/sample/sample_audvis-cov.fif", FIFFV_MNE_NOISE_COV);
const int ncovFile = noise->ncov;
auto noiseMeg = noise->pick_chs_omit(megNames, nMeg, false, ave.info.chs);
aveProj->apply_cov(noiseMeg.get());
noiseMeg->classify_channels(ave.info.chs, nMeg);
noiseMeg->decompose_eigen(); // the 3 projected directions become zero eigenvalues
VectorXf whitened(nMeg);
noiseMeg->whiten_vector(x, whitened, nMeg);

Public Methods​

MNECovMatrix(p_kind, p_ncov, p_names, p_cov, p_cov_diag, p_cov_sparse)​

Construct a covariance matrix.

Parameters:

  • p_kind : int Covariance kind (sensor or source).

  • p_ncov : int Dimension (number of channels).

  • p_names : const QStringList & Channel names.

  • p_cov : const Eigen::VectorXd & Packed lower-triangle data (may be empty).

  • p_cov_diag : const Eigen::VectorXd & Diagonal data (may be empty).

  • p_cov_sparse : *FiffSparseMatrix ** Sparse covariance data (may be nullptr).

~MNECovMatrix()​

Destructor.

dup()​

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

Returns:

  • std::unique_ptr< MNECovMatrix > — A newly allocated copy.

is_diag()​

Check whether this covariance matrix is stored in diagonal form.

Returns:

  • int — Non-zero if diagonal, zero if full or sparse.

add_inv()​

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

Returns:

  • int — OK on success, FAIL if neither diagonal nor decomposed.

condition(rank_threshold, use_rank)​

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

Parameters:

  • rank_threshold : float Eigenvalue threshold ratio for rank estimation.

  • use_rank : int If positive, override the automatic rank estimate.

Returns:

  • int — The estimated rank, or FAIL on error.

decompose_eigen_small(p_small, 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:

  • p_small : float Eigenvalue threshold (negative uses default).

  • use_rank : int If positive, override automatic rank estimate.

Returns:

  • int — OK on success, FAIL on error.

decompose_eigen()​

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

Returns:

  • int — OK on success, FAIL on error.

classify_channels(chs, nchan)​

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

Parameters:

  • chs : const QList< FiffChInfo > & Channel information list.

  • nchan : int Number of channels in chs.

Returns:

  • int — OK on success, FAIL if channel information is not available.

whiten_vector(data, whitened_data, nchan)​

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

Parameters:

  • data : Eigen::Ref< Eigen::VectorXf > Input data vector.

  • whitened_data : Eigen::Ref< Eigen::VectorXf > Whitened output vector (may alias data for in-place).

  • nchan : int Number of channels.

Returns:

  • int — OK on success, FAIL if dimensions are incompatible.

regularize(regs)​

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

Parameters:

  • regs : const Eigen::Vector3f & Regularization fractions for [MEG_MAG, MEG_GRAD, EEG].

revert_to_diag()​

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

pick_chs_omit(new_names, new_ncov, omit_meg_eeg, chs)​

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

Parameters:

  • new_names : const QStringList & Names of channels to pick.

  • new_ncov : int Number of channels to pick.

  • omit_meg_eeg : int If non-zero, zero out MEG-EEG cross entries.

  • chs : const QList< FiffChInfo > & Channel information list (for MEG/EEG classification).

Returns:

  • std::unique_ptr< MNECovMatrix > — A new covariance matrix with only the selected channels, or nullptr on error.

Static Methods​

create_dense(kind, ncov, names, cov)​

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

Parameters:

  • kind : int Covariance kind (sensor or source).

  • ncov : int Dimension (number of channels).

  • names : const QStringList & Channel names.

  • cov : const Eigen::VectorXd & Packed lower-triangle data (length ncov*(ncov+1)/2). Ownership transferred.

Returns:

  • std::unique_ptr< MNECovMatrix > — A new covariance matrix.

create_diag(kind, ncov, names, cov_diag)​

Create a diagonal covariance matrix.

Parameters:

  • kind : int Covariance kind (sensor or source).

  • ncov : int Dimension (number of channels).

  • names : const QStringList & Channel names.

  • cov_diag : const Eigen::VectorXd & Diagonal data (ncov elements).

Returns:

  • std::unique_ptr< MNECovMatrix > — A new covariance matrix.

create_sparse(kind, ncov, names, cov_sparse)​

Create a sparse covariance matrix.

Parameters:

  • kind : int Covariance kind (sensor or source).

  • ncov : int Dimension (number of channels).

  • names : const QStringList & Channel names.

  • cov_sparse : *FiffSparseMatrix ** Sparse covariance data (note: data are floats).

Returns:

  • std::unique_ptr< MNECovMatrix > — A new covariance matrix.

create(kind, ncov, names, cov, cov_diag)​

Create a covariance matrix from either dense or diagonal data.

Parameters:

  • kind : int Covariance kind (sensor or source).

  • ncov : int Dimension (number of channels).

  • names : const QStringList & Channel names.

  • cov : const Eigen::VectorXd & Packed lower-triangle data (may be empty).

  • cov_diag : const Eigen::VectorXd & Diagonal data (may be empty).

Returns:

  • std::unique_ptr< MNECovMatrix > — A new covariance matrix.

read(name, kind)​

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

Parameters:

  • name : const QString & Path to the FIFF file.

  • kind : int Covariance kind (e.g. FIFFV_MNE_SENSOR_COV).

Returns:

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

lt_packed_index(j, k)​

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

Parameters:

  • j : int Row index.

  • k : int Column index.

Returns:

  • int — The packed storage index.

Example​

Used in examples​

ex_mne_api​

MNE library: BEM surfaces, surface projection, ICP, source spaces and epochs.

src/examples/ex_mne_api/main.cpp, line 331
auto noise = MNECovMatrix::read(data + "/MEG/sample/sample_audvis-cov.fif", FIFFV_MNE_NOISE_COV);
const int ncovFile = noise->ncov;
auto noiseMeg = noise->pick_chs_omit(megNames, nMeg, false, ave.info.chs);
aveProj->apply_cov(noiseMeg.get());
noiseMeg->classify_channels(ave.info.chs, nMeg);
noiseMeg->decompose_eigen(); // the 3 projected directions become zero eigenvalues
VectorXf whitened(nMeg);
noiseMeg->whiten_vector(x, whitened, nMeg);
// mne.read_cov: 366 channels, nfree 15972; x^T pinv(P C P) x with P the 3 SSP vectors: 1462.05
ok &= expect(ncovFile == 366 && noise->nfree == 15972 && !noise->is_diag() && noiseMeg->nzero == 3 && near(whitened.cast<double>().squaredNorm(), 1462.0502702959539, 1e-4),
             "MNECovMatrix: projected noise covariance whitens like mne's pseudo-inverse");

Authors of this file​