Function read_annotations

mne/annotations.py:1798–1907

r"""Read annotations from a file. This function reads a ``.fif``, ``.fif.gz``, ``.vmrk``, ``.amrk``, ``.edf``, ``.bdf``, ``.gdf``, ``.txt``, ``.csv``, ``.cnt``, ``.cef``, or ``.set`` file and makes an :class:`mne.Annotations` object. Parameters ---------- fname : path-like

(
    fname,
    sfreq="auto",
    uint16_codec=None,
    encoding="utf8",
    ignore_marker_types=False,
    data_format="auto",
)

@fill_doc
def read_annotations(
    fname,
    sfreq="auto",
    uint16_codec=None,
    encoding="utf8",
    ignore_marker_types=False,
    data_format="auto",
) -> Annotations:
    r"""Read annotations from a file.

    This function reads a ``.fif``, ``.fif.gz``, ``.vmrk``, ``.amrk``,
    ``.edf``, ``.bdf``, ``.gdf``, ``.txt``, ``.csv``, ``.cnt``, ``.cef``, or
    ``.set`` file and makes an :class:`mne.Annotations` object.

    Parameters
    ----------
    fname : path-like
        The filename.
    sfreq : float | ``'auto'``
        The sampling frequency in the file. This parameter is necessary for
        \*.vmrk, \*.amrk, and \*.cef files as Annotations are expressed in
        seconds and \*.vmrk/\*.amrk/\*.cef files are in samples. For any other
        file format, ``sfreq`` is omitted. If set to 'auto' then the ``sfreq``
        is taken from the respective info file of the same name with according
        file extension (\*.vhdr/\*.ahdr for brainvision; \*.dap for Curry 7;
        \*.cdt.dpa for Curry 8). So data.vmrk/amrk looks for sfreq in
        data.vhdr/ahdr, data.cef looks in data.dap and data.cdt.cef looks in
        data.cdt.dpa.
    uint16_codec : str | None
        This parameter is only used in EEGLAB (\*.set) and omitted otherwise.
        If your \*.set file contains non-ascii characters, sometimes reading
        it may fail and give rise to error message stating that "buffer is
        too small". ``uint16_codec`` allows to specify what codec (for example:
        ``'latin1'`` or ``'utf-8'``) should be used when reading character
        arrays and can therefore help you solve this problem.
    %(encoding_edf)s
        Only used when reading EDF annotations.
    ignore_marker_types : bool
        If ``True``, ignore marker types in BrainVision files (and only use their
        descriptions). Defaults to ``False``.
    data_format : str
        Only used by CNT files, see :func:`mne.io.read_raw_cnt` for details.

    Returns
    -------
    annot : instance of Annotations
        The annotations.

    Notes
    -----
    The annotations stored in a ``.csv`` require the onset columns to be
    timestamps. If you have onsets as floats (in seconds), you should use the
    ``.txt`` extension.
    """
    from .io.brainvision.brainvision import _read_annotations_brainvision
    from .io.cnt.cnt import _read_annotations_cnt
    from .io.ctf.markers import _read_annotations_ctf
    from .io.curry.curry import _read_annotations_curry