Skip to main content

FiffEvents

Namespace: FIFFLIB  ·  Library: FIFF Library

#include <fiff/fiff_events.h>

class FIFFLIB::FiffEvents

FIFF event list: (sample, prev, new) integer triples with read / write / detect / filter helpers.

On-disk representation matches mne.io.write.write_events output and the -eve.fif files consumed by mne.read_events; the detection path mirrors mne.find_events. Used by FiffEpochs and the batch-averaging path in FiffEvokedSet to drive epoch extraction.

src/examples/ex_fiff_api/main.cpp
FiffEvents events;
FiffEvents::detect_from_raw(raw, events, "STI 014"); // rising edges of the trigger channel
QFile eventFile(tmp.filePath("sample-eve.fif"));
const bool eventsWritten = eventFile.open(QIODevice::WriteOnly) && events.write_to_fif(eventFile);
eventFile.close();
FiffEvents eventsBack(eventFile); // mne.read_events reads this file too

Public Methods​

FiffEvents()​

Default constructor.

Creates an empty event set.

FiffEvents(p_IODevice)​

Constructs FiffEvents by reading from an I/O device.

Attempts to read as FIFF first; if that fails, tries ASCII format.

Parameters:

  • p_IODevice : QIODevice & The I/O device to read from.

write_to_fif(p_IODevice)​

Write the event list to a FIFF file.

Parameters:

  • p_IODevice : QIODevice & The I/O device to write to.

Returns:

  • bool — true if succeeded, false otherwise.

write_to_ascii(p_IODevice, sfreq)​

Write the event list to a text file (MNE-C compatible format).

Parameters:

  • p_IODevice : QIODevice & The I/O device to write to.

  • sfreq : float Sampling frequency for time column computation.

Returns:

  • bool — true if succeeded, false otherwise.

num_events()​

Returns the number of events.

Returns:

  • int — Number of events.

is_empty()​

Returns true if no events are stored.

Returns:

  • bool — true if the event matrix has zero rows.

pick(include, exclude, step)​

Select events by code, like mne.pick_events.

Parameters:

  • include : const QList< int > & Codes to keep; if empty, all codes except exclude are kept.

  • exclude : const QList< int > & Codes to drop when include is empty.

  • step : bool Also match the code before the step (column 1).

Returns:

  • FiffEvents — The selected events in their original order.

merge(ids, newId, replaceEvents)​

Replace codes in both code columns by a new one, like mne.merge_events.

Parameters:

  • ids : const QList< int > & Codes to replace.

  • newId : int The new code.

  • replaceEvents : bool If false, the original events are kept as well, sorted by row.

Returns:

count(ids)​

Count the events per code (column 2), like mne.count_events.

Parameters:

  • ids : const QList< int > & Codes to report (0 if absent); if empty, every code that occurs.

Returns:

  • QMap< int, int > — Code to count.

Static Methods​

read(t_sEventName, t_fileRawName, p_Events)​

Read events from a FIFF or ASCII event file.

If t_sEventName is empty, the event file name is derived from the raw file name (replacing ".fif" with "-eve.fif").

Parameters:

  • t_sEventName : const QString & Path to the event file (empty = derive from raw file name).

  • t_fileRawName : const QString & Path to the raw data file (used to derive event file name if needed).

  • p_Events : FiffEvents & The loaded events.

Returns:

  • bool — true if succeeded, false otherwise.

read_from_fif(p_IODevice, p_Events)​

Read an event list from a FIFF file.

Parameters:

  • p_IODevice : QIODevice & The I/O device to read from.

  • p_Events : FiffEvents & The loaded events.

Returns:

  • bool — true if succeeded, false otherwise.

read_from_ascii(p_IODevice, p_Events)​

Read a list of events from an ASCII event file.

Parameters:

  • p_IODevice : QIODevice & The I/O device to read from.

  • p_Events : FiffEvents & The loaded events.

Returns:

  • bool — true if succeeded, false otherwise.

detect_from_raw(raw, p_Events, triggerCh, triggerMask, leadingEdge)​

Detect trigger events from raw data using a stimulus channel.

Ported from detect_events (MNE-C).

Parameters:

  • raw : const FiffRawData & The raw data.

  • p_Events : FiffEvents & The detected events.

  • triggerCh : const QString & Name of the trigger channel (empty = default "STI 014").

  • triggerMask : unsigned int Bitmask to apply to trigger values.

  • leadingEdge : bool If true, only detect rising edges (default = true).

Returns:

  • bool — true if events were detected, false otherwise.

matchEvent(cat, events, eventIdx)​

Check whether an event matches a category definition.

Parameters:

  • cat : const AverageCategory & The averaging category to match against.

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

  • eventIdx : int Index of the current event row.

Returns:

  • bool — true if the event matches.

concatenate(events, firstSamps, lastSamps)​

Concatenate the events of consecutive recordings, like mne.concatenate_events.

Parameters:

  • events : const QList< FiffEvents > & Events of each recording.

  • firstSamps : const QList< int > & First sample of each recording.

  • lastSamps : const QList< int > & Last sample of each recording.

Returns:

  • FiffEvents — Events on the sample axis of the concatenated recording (empty if the list lengths differ).

find_stim_steps(stimData, firstSamp, padStart, padStop, merge)​

Find the samples where all stimulus channels change at once, like mne.find_stim_steps.

Parameters:

  • stimData : const Eigen::MatrixXi & Stimulus channel data (channels x samples); steps carry the values of the first row.

  • firstSamp : int Sample number of the first column.

  • padStart : std::optional< int > If set, a step from this value at sample 0 is added when the data start elsewhere.

  • padStop : std::optional< int > If set, a step to this value after the last sample is added.

  • merge : int Merge steps at most |merge| samples apart (> 0: into the later, < 0: into the earlier).

Returns:

  • FiffEvents — Steps as [sample, value before, value after].

make_fixed_length(raw, id, start, stop, duration, firstSamp, overlap)​

Events at regular intervals, like mne.make_fixed_length_events.

Parameters:

  • raw : const FiffRawData & The recording.

  • id : int Event code.

  • start : double First event time in s.

  • stop : double Time in s after which no event may start (negative: end of the recording).

  • duration : double Duration of each segment in s.

  • firstSamp : bool Whether times count from the recording's first sample (true) or from 0.

  • overlap : double Overlap of consecutive segments in s, 0 <= overlap < duration.

Returns:

  • FiffEvents — The events (empty if none fit or the overlap is invalid).

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 174
FiffEvents events;
FiffEvents::detect_from_raw(raw, events, "STI 014"); // rising edges of the trigger channel
QFile eventFile(tmp.filePath("sample-eve.fif"));
const bool eventsWritten = eventFile.open(QIODevice::WriteOnly) && events.write_to_fif(eventFile);
eventFile.close();
FiffEvents eventsBack(eventFile); // mne.read_events reads this file too
// mne.find_events(raw, "STI 014"): 25 events, first [13988, 0, 2], [14172, 0, 3], [14385, 0, 1]
ok &= expect(events.num_events() == 25 && events.events.row(0) == RowVector3i(13988, 0, 2) && events.events.row(2) == RowVector3i(14385, 0, 1) && eventsWritten && eventsBack.events == events.events,
             "FiffEvents: 25 trigger events match mne.find_events and round-trip through -eve.fif");

ex_mne_api​

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

src/examples/ex_mne_api/main.cpp, line 232
QFile rawFile(data + "/MEG/sample/sample_audvis_trunc_raw.fif");
const FiffRawData raw(rawFile);
FiffEvents events;
FiffEvents::detect_from_raw(raw, events); // rising edges on STI 014
// Epochs of event 1 from -100 to 300 ms, no rejection
MNEEpochDataList epochs = MNEEpochDataList::readEpochs(raw, events.events, -0.1f, 0.3f, 1, {});
const MNEEpochData& firstEpoch = *epochs.first();
FiffEvoked evoked = epochs.average(raw.info, raw.first_samp, raw.last_samp);
// mne.Epochs(event_id=1, tmin=-0.1, tmax=0.3, baseline=None, proj=False): 6 epochs of 376 x 121, MEG 0113 first sample -7.5857e-15
ok &= expect(epochs.size() == 6 && firstEpoch.eventSample == 14385 && firstEpoch.epoch.rows() == 376 && firstEpoch.epoch.cols() == 121 && near(firstEpoch.epoch(0, 0), -7.585747577225703e-15, 1e-6) && near(firstEpoch.epoch.topRows(306).norm(), 7.05600718833613e-13, 1e-6),
             "MNEEpochDataList/MNEEpochData: 6 epochs of event 1 match mne.Epochs");
// mne Epochs.average(): |MEG| = 6.0801e-13 over 6 epochs, times from -99.898 to 299.693 ms with 0 at sample 30
ok &= expect(evoked.nave == 6 && near(evoked.data.topRows(306).norm(), 6.080119131626428e-13, 1e-6) && evoked.times.size() == 121 && near(evoked.times[0], -0.09989760657919393, 1e-6) && near(evoked.times[120], 0.2996928197375818, 1e-6) && evoked.times[30] == 0.0f,

Authors of this file​