Skip to main content

FiffEvokedSet

Namespace: FIFFLIB  ·  Library: FIFF Library

#include <fiff/fiff_evoked_set.h>

class FIFFLIB::FiffEvokedSet

Set of FiffEvoked instances sharing one FiffInfo, plus channel-picking and compensation helpers.

The on-disk shape of a *-ave.fif: one FiffInfo and one FiffEvoked per FIFFB_EVOKED block (one per averaging condition). Conversion utilities pick channels and shift compensation state across the whole set in lock-step.

src/examples/ex_fiff_api/main.cpp
QFile aveFile(dir + "/sample_audvis-ave.fif");
FiffEvokedSet evokedSet(aveFile); // all conditions of an -ave.fif file
const FiffEvoked& leftAuditory = evokedSet.evoked[0];

Public Methods​

FiffEvokedSet()​

Constructs a fiff evoked data set.

FiffEvokedSet(p_IODevice)​

Constructs a fiff evoked data set, by reading from a IO device.

Parameters:

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

FiffEvokedSet(p_FiffEvokedSet)​

Copy constructor.

Parameters:

  • p_FiffEvokedSet : const FiffEvokedSet & Fiff evoked data set which should be copied.

operator=(other)​

Copy assignment.

Every member has value semantics, so the compiler-generated member-wise assignment is correct. It is declared explicitly because declaring a copy constructor and/or a destructor deprecates the implicitly generated one.

Parameters:

Returns:

~FiffEvokedSet()​

Destroys the fiff evoked data set.

clear()​

Initializes fiff evoked data set.

pick_channels(include, exclude)​

fiff_pick_channels_evoked

Pick desired channels from evoked-response data

Parameters:

  • include : const QStringList &

    • Channels to include (if empty, include all available).

  • exclude : const QStringList &

    • Channels to exclude (if empty, do not exclude any).

Returns:

compensate_to(to)​

mne_compensate_to

Changes the CTF gradient compensation grade of all evoked responses in place.

Parameters:

  • to : fiff_int_t Desired compensation grade.

Returns:

  • bool — true if the data were changed, false if they already had that grade or it is not available.

find_evoked(p_FiffEvokedSet)​

fiff_find_evoked

Find evoked data sets

Parameters:

  • p_FiffEvokedSet : const FiffEvokedSet & The read evoked data set.

Returns:

  • bool — true when any set was found, false otherwise.

save(fileName)​

Save this evoked data set to a FIFF file.

Parameters:

  • fileName : const QString & Output file path.

Returns:

  • bool — true on success.

save(device)​

Save this evoked data set as FIFF to an I/O device, e.g.

a QBuffer.

Parameters:

  • device : QIODevice & The device to write to; it is opened for writing.

Returns:

  • bool — true on success.

Static Methods​

read(p_IODevice, p_FiffEvokedSet, baseline, proj)​

fiff_read_evoked

Wrapper for the FiffEvokedDataSet::read_evoked static function

Read one evoked data set

Parameters:

  • p_IODevice : QIODevice & An fiff IO device like a fiff QFile or QTCPSocket.

  • p_FiffEvokedSet : FiffEvokedSet & The read evoked data set.

  • baseline : QPair< float, float > The time interval to apply rescaling / baseline correction. If None do not apply it. If baseline is (a, b). the interval is between "a (s)" and "b (s)". If a is None the beginning of the data is used and if b is None then b is set to the end of the interval. If baseline is equal ot (None, None) all the time interval is used. If None, no correction is applied.

  • proj : bool Apply SSP projection vectors (optional, default = true).

Returns:

  • bool — true when successful, false otherwise.

computeGrandAverage(evokedSets)​

Compute a grand average across multiple evoked data sets (mne.grand_average with interpolate_bads=False, drop_bads=True).

For each category, channels marked bad in any set are dropped, the common channels are kept and the sets are combined with equal weights. nave is set to the number of sets and the comment to "Grand average (n = N)".

Parameters:

  • evokedSets : const QList< FiffEvokedSet > & List of evoked data sets to combine.

Returns:

  • FiffEvokedSet — The grand-average evoked set, or an empty set if input is empty.

computeAverages(raw, desc, events, log)​

Compute epoch-based averages from raw data according to an averaging description.

For each category in the description, matching events are epoched from the raw data, artifact-rejected, baseline-corrected, and averaged into a FiffEvoked entry.

Parameters:

  • raw : const FiffRawData & The raw data.

  • desc : const AverageDescription & The averaging description (categories, rejection, etc.).

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

  • log : QString & Processing log output.

Returns:

checkArtifacts(epoch, info, bads, rej, reason)​

Check whether an epoch passes artifact rejection criteria.

Parameters:

  • epoch : const Eigen::MatrixXd & Epoch data (nChannels x nSamples).

  • info : const FiffInfo & Channel info.

  • bads : const QStringList & List of bad channel names.

  • rej : const RejectionParams & Rejection parameters.

  • reason : QString & Rejection reason string (set only when rejected).

Returns:

  • bool — true if epoch is clean (not rejected).

subtractBaseline(epoch, bminSamp, bmaxSamp)​

Subtract baseline from each channel of an epoch.

For each row (channel), the mean of the samples in [bminSamp, bminSamp+nBase) is subtracted.

Parameters:

  • epoch : Eigen::MatrixXd & Data matrix (channels x samples) to correct in-place.

  • bminSamp : int First baseline sample (clamped to 0).

  • bmaxSamp : int Last baseline sample (clamped to epoch length - 1).

Example​

Used in examples​

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 155
RtAveragingWorker averager(10, 20, 80, 0, 0, 2, info); // up to 10 epochs, 20 pre / 80 post samples, trigger row 2
FiffEvokedSet evokedSet;
QObject::connect(&averager, &RtAveragingWorker::resultReady,
                 [&](const FiffEvokedSet& set, const QStringList&) { evokedSet = set; });
for (const MatrixXd& block : blocks) {
    averager.doWork(block); // runs synchronously; RtAveraging moves this worker to a thread
}
// Average of k = 1..4 is 2.5 after the trigger and 0 before it; MEG0121 stays at -2
bool avgOk = evokedSet.evoked.size() == 1;
if (avgOk) {
    const FiffEvoked& evoked = evokedSet.evoked.first();
    avgOk = evoked.nave == nBlocks && evoked.data.cols() == 100 && evoked.comment == "1" && std::fabs(evoked.data(0, 30) - 2.5) < 1e-12 && std::fabs(evoked.data(0, 10)) < 1e-12 && std::fabs(evoked.data(1, 60) + 2.0) < 1e-12 && std::fabs(evoked.times(20)) < 1e-6;
}

ex_inv_dipole_fit​

Inverse library: equivalent current dipole fitting in a sphere model.

src/examples/ex_inv_dipole_fit/main.cpp, line 115
// Hand the field to the pipeline as an evoked file with two samples.
QFile aveFile(sampleAve);
FiffEvokedSet evokedSet(aveFile);
FiffEvoked evoked = evokedSet.evoked[0].pick_channels(fitData->ch_names.mid(0, fitData->nmeg));
evoked.info.bads.clear();
evoked.data = field.cast<double>().replicate(1, 2);
evoked.first = 0;
evoked.last = 1;
evoked.times = RowVectorXf::LinSpaced(2, 0.0f, 1.0f / static_cast<float>(evoked.info.sfreq));
evoked.nave = 1;
FiffEvokedSet synthetic;
synthetic.info = evoked.info;
synthetic.evoked.append(evoked);
ok &= expect(synthetic.save(tmp.filePath("synthetic-ave.fif")), "FiffEvokedSet writes the synthetic field");

ex_fiff_api​

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

src/examples/ex_fiff_api/main.cpp, line 199
QFile aveFile(dir + "/sample_audvis-ave.fif");
FiffEvokedSet evokedSet(aveFile); // all conditions of an -ave.fif file
const FiffEvoked& leftAuditory = evokedSet.evoked[0];
// mne.read_evokeds: 4 conditions, "Left Auditory" nave 55, 376 x 421 samples starting at -0.1998 s
ok &= expect(evokedSet.evoked.size() == 4 && leftAuditory.comment == "Left Auditory" && leftAuditory.nave == 55 && leftAuditory.data.cols() == 421 && std::fabs(leftAuditory.times(0) + 0.19979521f) < 1e-6f,
             "FiffEvokedSet/FiffEvoked: 4 conditions; Left Auditory averages 55 epochs over 421 samples");

Also used in ex_cancel_noise, ex_evoked_grad_amp, ex_find_evoked, ex_mne_api.

Authors of this file​