Skip to main content

FiffCov

Namespace: FIFFLIB  ·  Library: FIFF Library

Python equivalent

mne.Covariance in MNE-Python.

#include <fiff/fiff_cov.h>

class FIFFLIB::FiffCov

FIFF noise / data covariance: matrix, channel names, kind, applied projectors, bads, dof and optional whitening eigendecomposition.

Round-trips with *-cov.fif files and with mne.Covariance in MNE-Python. Carries both the raw matrix and the metadata needed to regularize, project away SSP subspaces, and pre-whiten downstream forward / inverse computations.

src/examples/ex_fiff_api/main.cpp
QFile covFile(dir + "/sample_audvis-cov.fif");
FiffCov cov(covFile);
const FiffCov megCov = cov.pick_channels(info.ch_names.mid(0, 306), cov.bads); // good MEG channels only

Inheritance​

Public Methods​

FiffCov()​

Constructs the covariance data matrix.

FiffCov(p_IODevice)​

Constructs a covariance data matrix, by reading from a IO device.

Parameters:

  • p_IODevice : QIODevice & IO device to read from the evoked data set.

FiffCov(p_FiffCov)​

Copy constructor.

Parameters:

  • p_FiffCov : const FiffCov & Covariance data matrix which should be copied.

~FiffCov()​

Destroys the covariance data matrix.

clear()​

Initializes the covariance data matrix.

isEmpty()​

True if FIFF covariance is empty.

Returns:

  • bool — true if FIFF covariance is empty.

pick_channels(p_include, p_exclude)​

python pick_channels_cov

Pick channels from covariance matrix

Parameters:

  • p_include : const QStringList & List of channels to include (if empty, include all available). (optional).

  • p_exclude : const QStringList & Channels to exclude (if empty, do not exclude any). (optional).

Returns:

  • FiffCov — Covariance solution restricted to selected channels.

prepare_noise_cov(p_info, p_chNames)​

Prepare noise covariance matrix.

Before creating inverse operator.

Parameters:

  • p_info : const FiffInfo & measurement info.

  • p_chNames : const QStringList & Channels which should be taken into account.

Returns:

  • FiffCov — the prepared noise covariance matrix.

regularize(p_info, p_fMag, p_fGrad, p_fEeg, p_bProj, p_exclude)​

Regularize noise covariance matrix.

This method works by adding a constant to the diagonal for each channel type separatly. Special care is taken to keep the rank of the data constant.

Parameters:

  • p_info : const FiffInfo & The measurement info (used to get channel types and bad channels).

  • p_fMag : double Regularization factor for MEG magnetometers.

  • p_fGrad : double Regularization factor for MEG gradiometers.

  • p_fEeg : double Regularization factor for EEG.

  • p_bProj : bool Apply or not projections to keep rank of data.

  • p_exclude : QStringList List of channels to mark as bad. If None, bads channels are extracted from both info['bads'] and cov['bads'].

Returns:

  • FiffCov — the regularized covariance matrix.

save(fileName)​

Save this covariance matrix to a FIFF file.

Parameters:

  • fileName : const QString & Output file path.

Returns:

  • bool — true on success.

operator=(rhs)​

Assignment Operator.

Parameters:

Returns:

  • FiffCov & — the copied covariance matrix.

Static Methods​

read(p_IODevice, p_cov)​

Reads the noise covariance stored in a FIFF file, like mne.read_cov.

Parameters:

  • p_IODevice : QIODevice & IO device to read from.

  • p_cov : FiffCov & The covariance; unchanged when reading fails.

Returns:

  • bool — true when the device holds a noise covariance, false otherwise.

compute_from_epochs(raw, events, eventCodes, tmin, tmax, bmin, bmax, doBaseline, removeMean, ignoreMask, delay, rej)​

Compute a noise covariance matrix from raw data based on event-locked epochs.

Ported from compute_cov.c (MNE-C).

Parameters:

  • raw : const FiffRawData & The raw data.

  • events : const Eigen::MatrixXi & Event matrix (nEvents x 3): [sample, before, after].

  • eventCodes : const QList< int > & Which event codes to include.

  • tmin : float Start of time window relative to event (seconds).

  • tmax : float End of time window relative to event (seconds).

  • bmin : float Baseline start (seconds, relative to event). Only used if doBaseline is true.

  • bmax : float Baseline end (seconds, relative to event). Only used if doBaseline is true.

  • doBaseline : bool Whether to apply baseline correction before covariance computation.

  • removeMean : bool Whether to remove each event code's average response from the epochs (mne keep_sample_mean=False).

  • ignoreMask : unsigned int Bit mask ANDed away from event codes before matching (default: 0 = no masking).

  • delay : float Delay in seconds applied to the event sample before extracting the epoch (default: 0).

  • rej : *const RejectionParams ** If given, epochs failing these limits (before baseline, as MNE-C compute_cov) are skipped.

Returns:

  • FiffCov — The computed noise covariance matrix, or empty FiffCov on failure.

compute_from_epochs(epochs, info, removeMean)​

Compute a noise covariance matrix from epochs that are already in memory, e.g.

filtered ones.

Parameters:

  • epochs : const QList< QList< Eigen::MatrixXd > > & The epochs (channels x samples), grouped by event code.

  • info : const FiffInfo & Measurement info whose channels the epoch rows are.

  • removeMean : bool Whether to remove each group's average response (mne keep_sample_mean=False).

Returns:

  • FiffCov — The computed noise covariance matrix, or empty FiffCov on failure.

computeGrandAverage(covs)​

Compute a weighted grand-average covariance from multiple covariance matrices, weighting each by its degrees of freedom (nfree).

Parameters:

  • covs : const QList< FiffCov > & List of covariance matrices to combine.

Returns:

  • FiffCov — The grand-average covariance matrix, or empty FiffCov if covs is empty.

Example​

Used in examples​

ex_fiff_api​

FIFF library: measurement info, channels, digitizer, transforms, projectors, covariance, events,.

src/examples/ex_fiff_api/main.cpp, line 165
QFile covFile(dir + "/sample_audvis-cov.fif");
FiffCov cov(covFile);
const FiffCov megCov = cov.pick_channels(info.ch_names.mid(0, 306), cov.bads); // good MEG channels only
// mne.read_cov: dim 366, nfree 15972, 2 bads, 4 projectors, C[0, 0] = 2.272355891906954e-23
ok &= expect(cov.dim == 366 && cov.nfree == 15972 && cov.bads.size() == 2 && cov.projs.size() == 4 && near(cov.data(0, 0), 2.272355891906954e-23) && megCov.dim == 305,
             "FiffCov: 366 channels, 15972 degrees of freedom, C[0,0] matches mne.read_cov");

ex_dsp_rt​

DSP real-time workers: averaging, covariance, noise spectrum, connectivity, HPI fitting and inverse operators.

src/examples/ex_dsp_rt/main.cpp, line 196
RtCov rtCov(info);
FiffCov cov;
for (int start = 0; start < covData.cols(); start += 1000) {
    cov = rtCov.estimateCovariance(covData.middleCols(start, 1000), 4000); // empty until 4000 samples arrived
}
// regularize() adds 0.1 x mean MEG variance to the diagonal; the off-diagonal term is untouched
ok &= expect(cov.dim == 2 && cov.names == QStringList({"MEG0111", "MEG0121"}) && cov.nfree == 4000 && std::fabs(cov.data(0, 1) - numpyCov(0, 1)) < 1e-6 * std::fabs(numpyCov(0, 1)),
             QString("RtCov: covariance of 4000 samples matches numpy.cov off the diagonal (%1)").arg(cov.data(0, 1), 0, 'g', 6));

ex_inv_api​

Inverse library: minimum-norm estimates, resolution matrices, label time courses, sparse solvers.

src/examples/ex_inv_api/main.cpp, line 114
QFile fwdFile(data + "/Result/ref-sample_audvis-meg-eeg-oct-6-fwd.fif");
const MNEForwardSolution fwd = MNEForwardSolution(fwdFile).pick_regions({v1}); // 70 sources x 3 orientations
QFile covFile(data + "/MEG/sample/sample_audvis-cov.fif");
const FiffCov noiseCov(covFile);
QFile aveFile(data + "/MEG/sample/sample_audvis-ave.fif");
const FiffEvoked evoked(aveFile, 0); // "Left Auditory"

Also used in ex_inv_beamformer, ex_clustered_inverse_mne, ex_clustered_inverse_mne_raw, ex_connectivity, ex_connectivity_comparison, ex_disp_3D, ex_histogram, ex_inverse_mne_raw, ex_make_inverse_operator, ex_mne_api.

Authors of this file​