class_docstr: Raw data in FIF format.
  
  Parameters
  ----------
  fname : path-like | file-like
      The raw filename to load. For files that have automatically been split,
      the split part will be automatically loaded. Filenames not ending with
      ``raw.fif``, ``raw_sss.fif``, ``raw_tsss.fif``, ``_meg.fif``,
      ``_eeg.fif``,  or ``_ieeg.fif`` (with or without an optional additional
      ``.gz`` extension) will generate a warning. If a file-like object is
      provided, preloading must be used.
  
      .. versionchanged:: 0.18
         Support for file-like objects.
  allow_maxshield : bool | str (default False)
      If True, allow loading of data that has been recorded with internal
      active compensation (MaxShield). Data recorded with MaxShield should
      generally not be loaded directly, but should first be processed using
      SSS/tSSS to remove the compensation signals that may also affect brain
      activity. Can also be "yes" to load without eliciting a warning.
  %(preload)s
  %(on_split_missing)s
  %(verbose)s
  
  Attributes
  ----------
  %(info_not_none)s
  ch_names : list of string
      List of channels' names.
  n_times : int
      Total number of time points in the raw file.
  times :  ndarray
      Time vector in seconds. Starts from 0, independently of `first_samp`
      value. Time interval between consecutive time samples is equal to the
      inverse of the sampling frequency.
  preload : bool
      Indicates whether raw data are in memory.
  %(verbose)s
docstr: Read in header information from a raw file.
docstr_tok: ["Read","in","header","information","from","a","raw","file","."]
code: def _read_raw_file(
      self,
      fname,
      allow_maxshield,
      preload,
      do_check_ext=True,
      verbose=None,
  ):
      """Read in header information from a raw file."""
      logger.info("Opening raw data file %s..." % fname)
  
      #   Read in the whole file if preload is on and .fif.gz (saves time)
      if not _file_like(fname):
          if do_check_ext:
              endings = (
                  "raw.fif",
                  "raw_sss.fif",
                  "raw_tsss.fif",
                  "_meg.fif",
                  "_eeg.fif",
                  "_ieeg.fif",
              )
              endings += tuple([f"{e}.gz" for e in endings])
              check_fname(fname, "raw", endings)
          # filename
          fname = str(_check_fname(fname, "read", True, "fname"))
          ext = os.path.splitext(fname)[1].lower()
          whole_file = preload if ".gz" in ext else False
          del ext
      else:
          # file-like
          if not preload:
              raise ValueError(
                  "preload must be used with file-like objects"
              )
          whole_file = True
      fname_rep = _get_fname_rep(fname)
      ff, tree, _ = fiff_open(fname, preload=whole_file)
      with ff as fid:
          #   Read the measurement info
  
          info, meas = read_meas_info(fid, tree, clean_bads=True)
          annotations = _read_annotations_fif(fid, tree)
  
          #   Locate the data of interest
          raw_node = dir_tree_find(meas, FIFF.FIFFB_RAW_DATA)
          if len(raw_node) == 0:
              raw_node = dir_tree_find(meas, FIFF.FIFFB_CONTINUOUS_DATA)
              if len(raw_node) == 0:
                  raw_node = dir_tree_find(
                      meas, FIFF.FIFFB_IAS_RAW_DATA
                  )
                  if len(raw_node) == 0:
                      raise ValueError("No raw data in %s" % fname_rep)
                  _check_maxshield(allow_maxshield)
                  with info._unlock():
                      info["maxshield"] = True
          del meas
  
          if len(raw_node) == 1:
              raw_node = raw_node[0]
  
          #   Process the directory
          directory = raw_node["directory"]
          nent = raw_node["nent"]
          nchan = int(info["nchan"])
          first = 0
          first_samp = 0
          first_skip = 0
  
          #   Get first sample tag if it is there
          if directory[first].kind == FIFF.FIFF_FIRST_SAMPLE:
              tag = read_tag(fid, directory[first].pos)
              first_samp = int(tag.data.item())
              first += 1
              _check_entry(first, nent)
  
          #   Omit initial skip
          if directory[first].kind == FIFF.FIFF_DATA_SKIP:
              # This first skip can be applied only after we know the bufsize
              tag = read_tag(fid, directory[first].pos)
              first_skip = int(tag.data.item())
              first += 1
              _check_entry(first, nent)
  
          raw = _RawShell()
          raw.filename = fname
          raw.first_samp = first_samp
          if info["meas_date"] is None and annotations is not None:
              # we need to adjust annotations.onset as when there is no meas
              # date set_annotations considers that the origin of time is the
              # first available sample (ignores first_samp)
              annotations.onset -= first_samp / info["sfreq"]
          raw.set_annotations(annotations)
  
          #   Go through the remaining tags in the directory
          raw_extras = list()
          nskip = 0
          orig_format = None
  
          _byte_dict = {
              FIFF.FIFFT_DAU_PACK16: 2,
              FIFF.FIFFT_SHORT: 2,
              FIFF.FIFFT_FLOAT: 4,
              FIFF.FIFFT_DOUBLE: 8,
              FIFF.FIFFT_INT: 4,
              FIFF.FIFFT_COMPLEX_FLOAT: 8,
              FIFF.FIFFT_COMPLEX_DOUBLE: 16,
          }
          _orig_format_dict = {
              FIFF.FIFFT_DAU_PACK16: "short",
              FIFF.FIFFT_SHORT: "short",
              FIFF.FIFFT_FLOAT: "single",
              FIFF.FIFFT_DOUBLE: "double",
              FIFF.FIFFT_INT: "int",
              FIFF.FIFFT_COMPLEX_FLOAT: "single",
              FIFF.FIFFT_COMPLEX_DOUBLE: "double",
          }
  
          for k in range(first, nent):
              ent = directory[k]
              # There can be skips in the data (e.g., if the user unclicked)
              # an re-clicked the button
              if ent.kind == FIFF.FIFF_DATA_BUFFER:
                  #   Figure out the number of samples in this buffer
                  try:
                      div = _byte_dict[ent.type]
                  except KeyError:
                      raise RuntimeError(
                          f"Cannot handle data buffers of type {ent.type}"
                      ) from None
                  nsamp = ent.size // (div * nchan)
                  if orig_format is None:
                      orig_format = _orig_format_dict[ent.type]
  
                  #  Do we have an initial skip pending?
                  if first_skip > 0:
                      first_samp += nsamp * first_skip
                      raw.first_samp = first_samp
                      first_skip = 0
  
                  #  Do we have a skip pending?
                  if nskip > 0:
                      raw_extras.append(
                          dict(
                              ent=None,
                              first=first_samp,
                              nsamp=nskip * nsamp,
                              last=first_samp + nskip * nsamp - 1,
                          )
                      )
                      first_samp += nskip * nsamp
                      nskip = 0
  
                  #  Add a data buffer
                  raw_extras.append(
                      dict(
                          ent=ent,
                          first=first_samp,
                          last=first_samp + nsamp - 1,
                          nsamp=nsamp,
                      )
                  )
                  first_samp += nsamp
              elif ent.kind == FIFF.FIFF_DATA_SKIP:
                  tag = read_tag(fid, ent.pos)
                  nskip = int(tag.data.item())
  
          next_fname = _get_next_fname(fid, fname_rep, tree)
  
      # reformat raw_extras to be a dict of list/ndarray rather than
      # list of dict (faster access)
      raw_extras = {
          key: [r[key] for r in raw_extras] for key in raw_extras[0]
      }
      for key in raw_extras:
          if key != "ent":  # dict or None
              raw_extras[key] = np.array(raw_extras[key], int)
      if not np.array_equal(
          raw_extras["last"][:-1], raw_extras["first"][1:] - 1
      ):
          raise RuntimeError("FIF file appears to be broken")
      bounds = np.cumsum(
          np.concatenate([raw_extras["first"][:1], raw_extras["nsamp"]])
      )
      raw_extras["bounds"] = bounds
      assert len(raw_extras["bounds"]) == len(raw_extras["ent"]) + 1
      # store the original buffer size
      buffer_size_sec = np.median(raw_extras["nsamp"]) / info["sfreq"]
      del raw_extras["first"]
      del raw_extras["last"]
      del raw_extras["nsamp"]
  
      raw.last_samp = first_samp - 1
      raw.orig_format = orig_format
  
      #   Add the calibration factors
      cals = np.zeros(info["nchan"])
      for k in range(info["nchan"]):
          cals[k] = info["chs"][k]["range"] * info["chs"][k]["cal"]
  
      raw._cals = cals
      raw._raw_extras = raw_extras
      logger.info(
          "    Range : %d ... %d =  %9.3f ... %9.3f secs"
          % (
              raw.first_samp,
              raw.last_samp,
              float(raw.first_samp) / info["sfreq"],
              float(raw.last_samp) / info["sfreq"],
          )
      )
  
      raw.info = info
  
      logger.info("Ready.")
  
      return raw, next_fname, buffer_size_sec
  
imports: import copy
  import os
  import os.path
  import numpy
  from ..._fiff.constants import FIFF
  from ..._fiff.meas_info import read_meas_info
  from ..._fiff.open import _fiff_get_fid, _get_next_fname, fiff_open
  from ..._fiff.tag import _call_dict, read_tag
  from ..._fiff.tree import dir_tree_find
  from ..._fiff.utils import _mult_cal_one
  from ...annotations import Annotations, _read_annotations_fif
  from ...channels import fix_mag_coil_types
  from ...event import AcqParserFIF
  from ...utils import _check_fname, _file_like, _on_missing, check_fname, fill_doc, logger, verbose, warn
  from ..base import BaseRaw, _check_maxshield, _check_raw_compatibility, _get_fname_rep, _RawShell
label_desc: Use image node_id 2 for calling the Raw obj's underlying member method code with example usage: obj._read_raw_file(fname, allow_maxshield, preload, do_check_ext, verbose) and returns: raw,  next_fname,  buffer_size_sec