class_docstr: Mixin class for Annotations in Epochs.
class_docstr_tok: ["Mixin","class","for","Annotations","in","Epochs","."]
docstr: Add raw annotations into the Epochs metadata data frame.
  
  Adds three columns to the ``metadata`` consisting of a list
  in each row:
  - ``annot_onset``: the onset of each Annotation within
  the Epoch relative to the start time of the Epoch (in seconds).
  - ``annot_duration``: the duration of each Annotation
  within the Epoch in seconds.
  - ``annot_description``: the free-form text description of each
  Annotation.
  
  Parameters
  ----------
  overwrite : bool
      Whether to overwrite existing columns in metadata or not.
      Default is False.
  
  Returns
  -------
  self : instance of Epochs
      The modified instance (instance is also modified inplace).
  
  Notes
  -----
  .. versionadded:: 1.0
docstr_tok: ["Add","raw","annotations","into","the","Epochs","metadata","data","frame",".","Adds","three","columns","to","the","``","metadata","``","consisting","of","a","list","in","each","row",":","-","``","annot_onset","``",":","the","onset","of","each","Annotation","within","the","Epoch","relative","to","the","start","time","of","the","Epoch","(","in","seconds",")",".","-","``","annot_duration","``",":","the","duration","of","each","Annotation","within","the","Epoch","in","seconds",".","-","``","annot_description","``",":","the","free-form","text","description","of","each","Annotation",".","Parameters","--","--","--","--","--","overwrite",":","bool","Whether","to","overwrite","existing","columns","in","metadata","or","not",".","Default","is","False",".","Returns","--","--","--","-","self",":","instance","of","Epochs","The","modified","instance","(","instance","is","also","modified","inplace",")",".","Notes","--","--","-","..","versionadded",":",":","1.0"]
code: def add_annotations_to_metadata(self, overwrite=False):
      """Add raw annotations into the Epochs metadata data frame.
  
      Adds three columns to the ``metadata`` consisting of a list
      in each row:
      - ``annot_onset``: the onset of each Annotation within
      the Epoch relative to the start time of the Epoch (in seconds).
      - ``annot_duration``: the duration of each Annotation
      within the Epoch in seconds.
      - ``annot_description``: the free-form text description of each
      Annotation.
  
      Parameters
      ----------
      overwrite : bool
          Whether to overwrite existing columns in metadata or not.
          Default is False.
  
      Returns
      -------
      self : instance of Epochs
          The modified instance (instance is also modified inplace).
  
      Notes
      -----
      .. versionadded:: 1.0
      """
      pd = _check_pandas_installed()
  
      # check if annotations exist
      if self.annotations is None:
          warn(
              f"There were no Annotations stored in {self}, so "
              "metadata was not modified."
          )
          return self
  
      # get existing metadata DataFrame or instantiate an empty one
      if self._metadata is not None:
          metadata = self._metadata
      else:
          data = np.empty((len(self.events), 0))
          metadata = pd.DataFrame(data=data)
  
      if (
          any(
              name in metadata.columns
              for name in [
                  "annot_onset",
                  "annot_duration",
                  "annot_description",
              ]
          )
          and not overwrite
      ):
          raise RuntimeError(
              "Metadata for Epochs already contains columns "
              '"annot_onset", "annot_duration", or "annot_description".'
          )
  
      # get the Epoch annotations, then convert to separate lists for
      # onsets, durations, and descriptions
      epoch_annot_list = self.get_annotations_per_epoch()
      onset, duration, description = [], [], []
      for epoch_annot in epoch_annot_list:
          for ix, annot_prop in enumerate(
              (onset, duration, description)
          ):
              entry = [annot[ix] for annot in epoch_annot]
  
              # round onset and duration to avoid IO round trip mismatch
              if ix < 2:
                  entry = np.round(entry, decimals=12).tolist()
  
              annot_prop.append(entry)
  
      # Create a new Annotations column that is instantiated as an empty
      # list per Epoch.
      metadata["annot_onset"] = pd.Series(onset)
      metadata["annot_duration"] = pd.Series(duration)
      metadata["annot_description"] = pd.Series(description)
  
      # reset the metadata
      self.metadata = metadata
      return self
  
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 4 for calling the EpochAnnotationsMixin obj's underlying member method code with example usage: obj.add_annotations_to_metadata(overwrite) and returns: self, self