Skip to main content

FiffAnnotations

Namespace: FIFFLIB  ·  Library: FIFF Library  ·  Source: fiff/fiff_annotations.h

Python equivalent

mne.Annotations in MNE-Python.

#include <fiff/fiff_annotations.h>

class FIFFLIB::FiffAnnotations

Container for FiffAnnotation entries with FIFF, JSON and CSV serializers.

Read and written under FIFFB_MNE_ANNOTATIONS so the annotation list travels with the FIFF file. The JSON and CSV exporters let the same annotations be consumed by BIDS sidecars and by external scoring tools that do not understand FIFF directly.

src/examples/ex_fiff_api/main.cpp
MatrixXi firstThree = events.events.topRows(3);
FiffAnnotations annotations = annotationsFromEvents(firstThree, info.sfreq, {{1, "auditory/left"}, {2, "auditory/right"}}, raw.first_samp);
const FiffAnnotation blink{0.5, 1.0, "BAD_blink", {}, {}, {}}; // onset s, duration s, description, channels, ...
annotations.append(blink);
FiffAnnotations::write(tmp.filePath("annot.csv"), annotations);
const FiffAnnotations annotationsBack = FiffAnnotations::read(tmp.filePath("annot.csv"));
const MatrixXi eventsAgain = eventsFromAnnotations(annotationsBack.select("auditory"), info.sfreq, {{"auditory/left", 1}, {"auditory/right", 2}}, raw.first_samp);

Public Methods​

FiffAnnotations()​

Constructs an empty FiffAnnotations object.

size()​

Returns the number of annotations.

Returns:

  • int — Number of annotations.

isEmpty()​

Returns true if no annotations are stored.

Returns:

  • bool — True if empty.

operator[](index)​

Const subscript operator.

Parameters:

  • index : int Index of the annotation.

Returns:

operator[](index)​

Subscript operator.

Parameters:

  • index : int Index of the annotation.

Returns:

append(annotation)​

Appends an annotation.

Parameters:

append(onset, duration, description, channelNames, comment)​

Appends an annotation by fields.

Parameters:

  • onset : double Onset in seconds.

  • duration : double Duration in seconds.

  • description : const QString & Description label.

  • channelNames : const QStringList & Channel names (empty for global).

  • comment : const QString & Optional comment.

remove(index)​

Removes the annotation at the given index.

Parameters:

  • index : int Index to remove.

clear()​

Removes all annotations.

toVector()​

Returns a const reference to the underlying vector.

Returns:

  • const QVector< FiffAnnotation > & — Const reference to annotation vector.

onsetToSample(index, sfreq, firstSample)​

Converts onset of annotation at index to a sample number.

Parameters:

  • index : int Annotation index.

  • sfreq : double Sampling frequency in Hz.

  • firstSample : int First sample offset.

Returns:

  • int — Sample number.

endToSample(index, sfreq, firstSample)​

Converts end (onset+duration) of annotation at index to a sample number.

Parameters:

  • index : int Annotation index.

  • sfreq : double Sampling frequency in Hz.

  • firstSample : int First sample offset.

Returns:

  • int — Sample number.

select(descriptionFilter)​

Selects annotations whose description starts with the filter string.

Parameters:

  • descriptionFilter : const QString & Prefix to match.

Returns:

selectByChannel(channelName)​

Selects annotations that reference the given channel name.

Parameters:

  • channelName : const QString & Channel name to match.

Returns:

crop(tmin, tmax)​

Returns annotations overlapping [tmin, tmax], clipping partially overlapping ones.

Parameters:

  • tmin : double Start time in seconds.

  • tmax : double End time in seconds.

Returns:

Static Methods​

readJson(path)​

Reads annotations from a JSON file.

Parameters:

  • path : const QString & File path.

Returns:

writeJson(path, annot)​

Writes annotations to a JSON file.

Parameters:

  • path : const QString & File path.

  • annot : const FiffAnnotations & Annotations to write.

Returns:

  • bool — True on success.

readCsv(path)​

Reads annotations from a CSV file.

Parameters:

  • path : const QString & File path.

Returns:

writeCsv(path, annot)​

Writes annotations to a CSV file.

Parameters:

  • path : const QString & File path.

  • annot : const FiffAnnotations & Annotations to write.

Returns:

  • bool — True on success.

read(path)​

Auto-detects format and reads annotations.

Parameters:

  • path : const QString & File path (.json or .csv).

Returns:

write(path, annot)​

Auto-detects format and writes annotations.

Parameters:

  • path : const QString & File path (.json or .csv).

  • annot : const FiffAnnotations & Annotations to write.

Returns:

  • bool — True on success.

Example​

Used in examples​

ex_fiff_api​

FIFF library: measurement info, channels, digitizer, transforms, projectors, covariance, events, annotations, evoked sets and the low-level file structure.

src/examples/ex_fiff_api/main.cpp, line 186
MatrixXi firstThree = events.events.topRows(3);
FiffAnnotations annotations = annotationsFromEvents(firstThree, info.sfreq, {{1, "auditory/left"}, {2, "auditory/right"}}, raw.first_samp);
const FiffAnnotation blink{0.5, 1.0, "BAD_blink", {}, {}, {}}; // onset s, duration s, description, channels, ...
annotations.append(blink);
FiffAnnotations::write(tmp.filePath("annot.csv"), annotations);
const FiffAnnotations annotationsBack = FiffAnnotations::read(tmp.filePath("annot.csv"));
const MatrixXi eventsAgain = eventsFromAnnotations(annotationsBack.select("auditory"), info.sfreq, {{"auditory/left", 1}, {"auditory/right", 2}}, raw.first_samp);
// Event 13988 (code 2) is (13988 - 12900) / 300.307 s = 3.6230 s after the first sample; code 3 has no description and stays "3"; the CSV keeps onsets to well within half a sample
ok &= expect(annotationsBack.size() == 4 && std::fabs(annotationsBack.select("auditory/right").toVector()[0].onset - (13988 - 12900) / info.sfreq) < 0.5 / info.sfreq && eventsAgain.rows() == 2 && eventsAgain(0, 0) == 13988 && eventsAgain(1, 0) == 14385 && eventsAgain(1, 2) == 1 && annotationsBack.select("3").size() == 1,
             "FiffAnnotations: events become onsets in seconds and back, with descriptions as codes");

ex_dsp_artifacts​

Artifact detection and repair with the dsp library on a recording with planted defects.

src/examples/ex_dsp_artifacts/main.cpp, line 222
AnnotateAmplitudeParams amplitude;
amplitude.flat = 1e-12; // consecutive samples within 1 pV of each other
QStringList flatChannels;
const FiffAnnotations flatSpans = annotateAmplitude(loose, info, kSFreq, amplitude, &flatChannels);
ok &= expect(flatSpans.size() == 1 && flatSpans[0].description == "BAD_flat" && std::abs(flatSpans[0].onset - 1.0) < 1e-12 && flatChannels == QStringList({"EEG2"}),
             QString("annotateAmplitude: %1 flat span(s), bad %2").arg(flatSpans.size()).arg(flatChannels.join(", ")));

Authors of this file​