Skip to main content

MNENamedMatrix

Namespace: MNELIB  ·  Library: MNE Library

#include <mne/mne_named_matrix.h>

class MNELIB::MNENamedMatrix

A dense matrix with named rows and columns.

MNENamedMatrix associates a dense float matrix (Eigen::MatrixXf) with optional row and column name lists (QStringList). It is the C++ equivalent of the MNE-C mneNamedMatrixRec struct, and is used throughout the library to represent projection vectors, CTF compensation matrices, and forward-solution gain matrices.

The class provides factory methods to:

  • build() a matrix from its constituent parts,
  • read() a matrix from a FIFF stream, and
  • pick() a sub-matrix by selecting named rows and/or columns.

All factory methods return std::unique_ptr<MNENamedMatrix> for clear ownership.

src/examples/ex_mne_api/main.cpp
// Open a third-order gradiometer recording and read it uncompensated (grade 0)
std::unique_ptr<MNERawData> ctfRaw(MNERawData::open_file_comp(ctfPath, false, false, MNEFilterDef(), 0));
const MNECTFCompDataSet& comp = *ctfRaw->comp; // grades 1, 2, 3 and two 4D kinds
const MNECTFCompData* third = nullptr;
for (const auto& c : comp.comps) {
    if (c->kind == MNECTFCompDataSet::map_comp_kind(3)) {
        third = c.get();
    }
}
const int grade = MNECTFCompDataSet::get_comp(ctfRaw->info->chInfo, ctfRaw->info->nchan);
Matrix<float, Dynamic, Dynamic, RowMajor> ctf(ctfRaw->info->nchan, 21);
std::vector<float*> ctfRows(ctf.rows());
for (int c = 0; c < ctf.rows(); ++c) {
    ctfRows[c] = ctf.row(c).data();
}
ctfRaw->pick_data(nullptr, ctfRaw->first_samp, 21, ctfRows.data());

Public Methods​

MNENamedMatrix()​

Default constructor.

Creates an empty named matrix with zero rows and columns and no associated name lists.

MNENamedMatrix(p_MneNamedMatrix)​

Copy constructor.

Performs a deep copy of all members: dimensions, name lists, and matrix data.

Parameters:

  • p_MneNamedMatrix : const MNENamedMatrix & The named matrix to copy.

~MNENamedMatrix()​

Destructor.

All members (Eigen::MatrixXf, QStringList) are value types and clean themselves up automatically.

pick(pickrowlist, picknrow, pickcollist, pickncol)​

Create a sub-matrix by picking named rows and columns.

Selects a subset of this matrix's rows and columns by matching their names against the supplied pick-lists. If a pick-list is empty, all rows (or columns) of the original are retained.

Parameters:

  • pickrowlist : const QStringList & Row names to select (empty = keep all rows).

  • picknrow : int Expected number of picked rows (used when pickrowlist is empty).

  • pickcollist : const QStringList & Column names to select (empty = keep all columns).

  • pickncol : int Expected number of picked columns (used when pickcollist is empty).

Returns:

  • std::unique_ptr< MNENamedMatrix > — A unique pointer to the picked sub-matrix, or nullptr if a requested name was not found.

Static Methods​

build(nrow, ncol, rowlist, collist, data)​

Factory: build a named matrix from its constituent parts.

Assembles an MNENamedMatrix from dimension counts, optional row/column name lists, and a dense data matrix.

Parameters:

  • nrow : int Number of rows (must match data.rows()).

  • ncol : int Number of columns (must match data.cols()).

  • rowlist : const QStringList & Name list for the rows (may be empty).

  • collist : const QStringList & Name list for the columns (may be empty).

  • data : const Eigen::MatrixXf & Dense float matrix to store.

Returns:

  • std::unique_ptr< MNENamedMatrix > — A unique pointer to the newly created named matrix.

read(stream, node, kind)​

Factory: read a named matrix from a FIFF file.

Reads a two-dimensional tagged matrix of the given kind from node (or its first FIFFB_MNE_NAMED_MATRIX child). Row and column name lists are read from the associated FIFF_MNE_ROW_NAMES and FIFF_MNE_COL_NAMES tags when present.

Parameters:

  • stream : QSharedPointer<FiffStream> & Open FIFF stream to read from.

  • node : const QSharedPointer<FiffDirNode> & Directory node that contains (or is) the named-matrix block.

  • kind : int FIFF tag kind that identifies the matrix data (e.g. FIFF_MNE_FORWARD_SOLUTION).

Returns:

  • std::unique_ptr< MNENamedMatrix > — A unique pointer to the read matrix, or nullptr on failure.

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 362
// raw.apply_gradient_compensation(0): sum |MEG| over the 7 MEG channels 2.45885e-10 (1.47942e-11 as stored)
ok &= expect(comp.ncomp == 5 && grade == 0 && third && MNECTFCompDataSet::explain_comp(third->kind) == "third order gradiometer" && third->data->nrow == 7 && near(ctf.topRows(7).cast<double>().cwiseAbs().sum(), 2.4588499274586883e-10, 1e-5),
             "MNECTFCompDataSet/MNECTFCompData/MNENamedMatrix: grade 3 -> 0 like raw.apply_gradient_compensation");

Authors of this file​