mne.Annotations

class mne.Annotations(onset, duration, description, orig_time=None)

Annotation object for annotating segments of raw data.

Parameters

onsetarray of float, shape (n_annotations,)

The starting time of annotations in seconds after orig_time.

durationarray of float, shape (n_annotations,)

Durations of the annotations in seconds.

descriptionarray of str, shape (n_annotations,) | str

Array of strings containing description for each annotation. If a string, all the annotations are given the same description. To reject epochs, use description starting with keyword ‘bad’. See example above.

orig_timefloat | int | instance of datetime.datetime | array of int | None | str

A POSIX Timestamp, datetime or an array containing the timestamp as the first element and microseconds as the second element. Determines the starting time of annotation acquisition. If None (default), starting time is determined from beginning of raw data acquisition. In general, raw.info['meas_date'] (or None) can be used for syncing the annotations with raw data if their acquisiton is started at the same time. If it is a string, it should conform to the ISO8601 format. More precisely to this ‘%Y-%m-%d %H:%M:%S.%f’ particular case of the ISO8601 format where the delimiter between date and time is ‘ ‘.

Notes

Annotations are added to instance of mne.io.Raw as the attribute raw.annotations.

To reject bad epochs using annotations, use annotation description starting with ‘bad’ keyword. The epochs with overlapping bad segments are then rejected automatically by default.

To remove epochs with blinks you can do:

>>> eog_events = mne.preprocessing.find_eog_events(raw)  
>>> n_blinks = len(eog_events)  
>>> onset = eog_events[:, 0] / raw.info['sfreq'] - 0.25  
>>> duration = np.repeat(0.5, n_blinks)  
>>> description = ['bad blink'] * n_blinks  
>>> annotations = mne.Annotations(onset, duration, description)  
>>> raw.set_annotations(annotations)  
>>> epochs = mne.Epochs(raw, events, event_id, tmin, tmax)  

orig_time

If orig_time is None, the annotations are synced to the start of the data (0 seconds). Otherwise the annotations are synced to sample 0 and raw.first_samp is taken into account the same way as with events.

When setting annotations, the following alignments between raw.info['meas_date'] and annotation.orig_time take place:

----------- meas_date=XX, orig_time=YY -----------------------------

     |              +------------------+
     |______________|     RAW          |
     |              |                  |
     |              +------------------+
 meas_date      first_samp
     .
     .         |         +------+
     .         |_________| ANOT |
     .         |         |      |
     .         |         +------+
     .     orig_time   onset[0]
     .
     |                   +------+
     |___________________|      |
     |                   |      |
     |                   +------+
 orig_time            onset[0]'

----------- meas_date=XX, orig_time=None ---------------------------

     |              +------------------+
     |______________|     RAW          |
     |              |                  |
     |              +------------------+
     .              N         +------+
     .              o_________| ANOT |
     .              n         |      |
     .              e         +------+
     .
     |                        +------+
     |________________________|      |
     |                        |      |
     |                        +------+
 orig_time                 onset[0]'

----------- meas_date=None, orig_time=YY ---------------------------

     N              +------------------+
     o______________|     RAW          |
     n              |                  |
     e              +------------------+
               |         +------+
               |_________| ANOT |
               |         |      |
               |         +------+

            [[[ CRASH ]]]

----------- meas_date=None, orig_time=None -------------------------

     N              +------------------+
     o______________|     RAW          |
     n              |                  |
     e              +------------------+
     .              N         +------+
     .              o_________| ANOT |
     .              n         |      |
     .              e         +------+
     .
     N                        +------+
     o________________________|      |
     n                        |      |
     e                        +------+
 orig_time                 onset[0]'

Methods

__add__(self, other)	Add (concatencate) two Annotation objects.
__getitem__(self, key)	Propagate indexing and slicing to the underlying numpy structure.
__hash__(self, /)	Return hash(self).
__iter__(self)	Iterate over the annotations.
__len__(self)	Return the number of annotations.
append(self, onset, duration, description)	Add an annotated segment.
copy(self)	Return a deep copy of self.
crop(self[, tmin, tmax, emit_warning])	Remove all annotation that are outside of [tmin, tmax].
delete(self, idx)	Remove an annotation.
save(self, fname)	Save annotations to FIF, CSV or TXT.

__add__(self, other)

Add (concatencate) two Annotation objects.

__getitem__(self, key)

Propagate indexing and slicing to the underlying numpy structure.

__hash__(self, /)

Return hash(self).

__iter__(self)

Iterate over the annotations.

__len__(self)

Return the number of annotations.

append(self, onset, duration, description)

Add an annotated segment. Operates inplace.

Parameters

onsetfloat | array_like

Annotation time onset from the beginning of the recording in seconds.

durationfloat | array_like

Duration of the annotation in seconds.

descriptionstr | array_like

Description for the annotation. To reject epochs, use description starting with keyword ‘bad’

Returns

selfmne.Annotations

The modified Annotations object.

Notes

The array-like support for arguments allows this to be used similarly to not only list.append, but also list.extend.

copy(self)

Return a deep copy of self.

crop(self, tmin=None, tmax=None, emit_warning=False)

Remove all annotation that are outside of [tmin, tmax].

The method operates inplace.

Parameters

tminfloat | None

Start time of selection in seconds.

tmaxfloat | None

End time of selection in seconds.

emit_warningbool

Whether to emit warnings when limiting or omitting annotations. Defaults to False.

Returns

selfinstance of Annotations

The cropped Annotations object.

delete(self, idx)

Remove an annotation. Operates inplace.

Parameters

idxint | array_like of int

Index of the annotation to remove. Can be array-like to remove multiple indices.

save(self, fname)

Save annotations to FIF, CSV or TXT.

Typically annotations get saved in the FIF file for raw data (e.g., as raw.annotations), but this offers the possibility to also save them to disk separately in different file formats which are easier to share between packages.

Parameters

fnamestr

The filename to use.

Examples using mne.Annotations

Parsing events from raw data

Annotating continuous data

Rejecting bad data spans

Brainstorm auditory tutorial dataset

Sleep stage classification from polysomnography (PSG) data