class_docstr: Annotation object for annotating segments of raw data.
  
  .. note::
     To convert events to `~mne.Annotations`, use
     `~mne.annotations_from_events`. To convert existing `~mne.Annotations`
     to events, use  `~mne.events_from_annotations`.
  
  Parameters
  ----------
  onset : array of float, shape (n_annotations,)
      The starting time of annotations in seconds after ``orig_time``.
  duration : array of float, shape (n_annotations,) | float
      Durations of the annotations in seconds. If a float, all the
      annotations are given the same duration.
  description : array 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_time : float | str | datetime | tuple of int | None
      A POSIX Timestamp, datetime or a tuple 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 acquisition 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 ' '.
  %(ch_names_annot)s
  
      .. versionadded:: 0.23
  
  See Also
  --------
  mne.annotations_from_events
  mne.events_from_annotations
  
  Notes
  -----
  Annotations are added to instance of :class:`mne.io.Raw` as the attribute
  :attr:`raw.annotations <mne.io.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)  # doctest: +SKIP
  >>> n_blinks = len(eog_events)  # doctest: +SKIP
  >>> onset = eog_events[:, 0] / raw.info['sfreq'] - 0.25  # doctest: +SKIP
  >>> duration = np.repeat(0.5, n_blinks)  # doctest: +SKIP
  >>> description = ['bad blink'] * n_blinks  # doctest: +SKIP
  >>> annotations = mne.Annotations(onset, duration, description)  # doctest: +SKIP
  >>> raw.set_annotations(annotations)  # doctest: +SKIP
  >>> epochs = mne.Epochs(raw, events, event_id, tmin, tmax)  # doctest: +SKIP
  
  **ch_names**
  
  Specifying channel names allows the creation of channel-specific
  annotations. Once the annotations are assigned to a raw instance with
  :meth:`mne.io.Raw.set_annotations`, if channels are renamed by the raw
  instance, the annotation channels also get renamed. If channels are dropped
  from the raw instance, any channel-specific annotation that has no channels
  left in the raw instance will also be removed.
  
  **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]'
  
  .. warning::
     This means that when ``raw.info['meas_date'] is None``, doing
     ``raw.set_annotations(raw.annotations)`` will not alter ``raw`` if and
     only if ``raw.first_samp == 0``. When it's non-zero,
     ``raw.set_annotations`` will assume that the "new" annotations refer to
     the original data (with ``first_samp==0``), and will be re-referenced to
     the new time offset!
  
  **Specific annotation**
  
  ``BAD_ACQ_SKIP`` annotation leads to specific reading/writing file
  behaviours. See :meth:`mne.io.read_raw_fif` and
  :meth:`Raw.save() <mne.io.Raw.save>` notes for details.
class_docstr_tok: ["Annotation","object","for","annotating","segments","of","raw","data",".","..","note",":",":","To","convert","events","to","`","~mne.Annotations","`",",","use","`","~mne.annotations_from_events","`",".","To","convert","existing","`","~mne.Annotations","`","to","events",",","use","`","~mne.events_from_annotations","`",".","Parameters","--","--","--","--","--","onset",":","array","of","float",",","shape","(","n_annotations",",",")","The","starting","time","of","annotations","in","seconds","after","``","orig_time","``",".","duration",":","array","of","float",",","shape","(","n_annotations",",",")","|","float","Durations","of","the","annotations","in","seconds",".","If","a","float",",","all","the","annotations","are","given","the","same","duration",".","description",":","array","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_time",":","float","|","str","|","datetime","|","tuple","of","int","|","None","A","POSIX","Timestamp",",","datetime","or","a","tuple","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","acquisition","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","'","'",".","%","(","ch_names_annot",")","s","..","versionadded",":",":","0.23","See","Also","--","--","--","--","mne.annotations_from_events","mne.events_from_annotations","Notes","--","--","-","Annotations","are","added","to","instance","of",":","class",":","`","mne.io.Raw","`","as","the","attribute",":","attr",":","`","raw.annotations","<","mne.io.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",")","#","doctest",":","+SKIP",">",">",">","n_blinks","=","len","(","eog_events",")","#","doctest",":","+SKIP",">",">",">","onset","=","eog_events","[",":",",","0","]","\/","raw.info","[","'sfreq","'","]","-","0.25","#","doctest",":","+SKIP",">",">",">","duration","=","np.repeat","(","0.5",",","n_blinks",")","#","doctest",":","+SKIP",">",">",">","description","=","[","'bad","blink","'","]","*","n_blinks","#","doctest",":","+SKIP",">",">",">","annotations","=","mne.Annotations","(","onset",",","duration",",","description",")","#","doctest",":","+SKIP",">",">",">","raw.set_annotations","(","annotations",")","#","doctest",":","+SKIP",">",">",">","epochs","=","mne.Epochs","(","raw",",","events",",","event_id",",","tmin",",","tmax",")","#","doctest",":","+SKIP","*","*","ch_names","*","*","Specifying","channel","names","allows","the","creation","of","channel-specific","annotations",".","Once","the","annotations","are","assigned","to","a","raw","instance","with",":","meth",":","`","mne.io.Raw.set_annotations","`",",","if","channels","are","renamed","by","the","raw","instance",",","the","annotation","channels","also","get","renamed",".","If","channels","are","dropped","from","the","raw","instance",",","any","channel-specific","annotation","that","has","no","channels","left","in","the","raw","instance","will","also","be","removed",".","*","*","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","]","'","..","warning",":",":","This","means","that","when","``","raw.info","[","'meas_date","'","]","is","None","``",",","doing","``","raw.set_annotations","(","raw.annotations",")","``","will","not","alter","``","raw","``","if","and","only","if","``","raw.first_samp","==","0","``",".","When","it","'s","non-zero",",","``","raw.set_annotations","``","will","assume","that","the","``","new","''","annotations","refer","to","the","original","data","(","with","``","first_samp==0","``",")",",","and","will","be","re-referenced","to","the","new","time","offset","!","*","*","Specific","annotation","*","*","``","BAD_ACQ_SKIP","``","annotation","leads","to","specific","reading\/writing","file","behaviours",".","See",":","meth",":","`","mne.io.read_raw_fif","`","and",":","meth",":","`","Raw.save","(",")","<","mne.io.Raw.save",">","`","notes","for","details","."]
docstr: Export annotations in tabular structure as a pandas DataFrame.
  
  Parameters
  ----------
  %(time_format_df_raw)s
  
      .. versionadded:: 1.7
  
  Returns
  -------
  result : pandas.DataFrame
      Returns a pandas DataFrame with onset, duration, and
      description columns. A column named ch_names is added if any
      annotations are channel-specific.
docstr_tok: ["Export","annotations","in","tabular","structure","as","a","pandas","DataFrame",".","Parameters","--","--","--","--","--","%","(","time_format_df_raw",")","s","..","versionadded",":",":","1.7","Returns","--","--","--","-","result",":","pandas.DataFrame","Returns","a","pandas","DataFrame","with","onset",",","duration",",","and","description","columns",".","A","column","named","ch_names","is","added","if","any","annotations","are","channel-specific","."]
code: def to_data_frame(self, time_format="datetime"):
      """Export annotations in tabular structure as a pandas DataFrame.
  
      Parameters
      ----------
      %(time_format_df_raw)s
  
          .. versionadded:: 1.7
  
      Returns
      -------
      result : pandas.DataFrame
          Returns a pandas DataFrame with onset, duration, and
          description columns. A column named ch_names is added if any
          annotations are channel-specific.
      """
      pd = _check_pandas_installed(strict=True)
      valid_time_formats = ["ms", "timedelta", "datetime"]
      dt = _handle_meas_date(self.orig_time)
      if dt is None:
          dt = _handle_meas_date(0)
      time_format = _check_time_format(
          time_format, valid_time_formats, dt
      )
      dt = dt.replace(tzinfo=None)
      times = _convert_times(self.onset, time_format, dt)
      df = dict(
          onset=times,
          duration=self.duration,
          description=self.description,
      )
      if self._any_ch_names():
          df.update(ch_names=self.ch_names)
      df = pd.DataFrame(df)
      return df
  
imports: import json
  import os.path
  import re
  import warnings
  from collections import Counter, OrderedDict
  from collections.abc import Iterable
  from copy import deepcopy
  from datetime import datetime, timedelta, timezone
  from itertools import takewhile
  from textwrap import shorten
  import numpy
  from scipy.io import loadmat
  from ._fiff.constants import FIFF
  from ._fiff.open import fiff_open
  from ._fiff.tag import read_tag
  from ._fiff.tree import dir_tree_find
  from ._fiff.write import _safe_name_list, end_block, start_and_end_file, start_block, write_double, write_float, write_name_list_sanitized, write_string
  from .utils import _check_dict_keys, _check_dt, _check_fname, _check_option, _check_pandas_installed, _check_time_format, _convert_times, _DefaultEventParser, _dt_to_stamp, _is_numeric, _mask_to_onsets_offsets, _on_missing, _pl, _stamp_to_dt, _validate_type, check_fname, fill_doc, int_like, logger, verbose, warn
label_desc: Use image node_id 13 for calling the Annotations obj's underlying member method code with example usage: obj.to_data_frame(time_format) and returns: df