class_docstr: Raw object from Artemis123 file.
  
  Parameters
  ----------
  input_fname : path-like
      Path to the Artemis123 data file (ending in ``'.bin'``).
  %(preload)s
  %(verbose)s
  
  See Also
  --------
  mne.io.Raw : Documentation of attributes and methods.
class_docstr_tok: ["Raw","object","from","Artemis123","file",".","Parameters","--","--","--","--","--","input_fname",":","path-like","Path","to","the","Artemis123","data","file","(","ending","in","``","'.bin","'","``",")",".","%","(","preload",")","s","%","(","verbose",")","s","See","Also","--","--","--","--","mne.io.Raw",":","Documentation","of","attributes","and","methods","."]
code: def __init__(
      self,
      input_fname,
      preload=False,
      verbose=None,
      pos_fname=None,
      add_head_trans=True,
  ):
      from ...chpi import (
          _fit_coil_order_dev_head_trans,
          compute_chpi_amplitudes,
          compute_chpi_locs,
      )
  
      input_fname = str(
          _check_fname(input_fname, "read", True, "input_fname")
      )
      fname, ext = op.splitext(input_fname)
      if ext == ".txt":
          input_fname = fname + ".bin"
      elif ext != ".bin":
          raise RuntimeError(
              'Valid artemis123 files must end in "txt"' + ' or ".bin".'
          )
  
      if not op.exists(input_fname):
          raise RuntimeError("%s - Not Found" % input_fname)
  
      info, header_info = _get_artemis123_info(
          input_fname, pos_fname=pos_fname
      )
  
      last_samps = [header_info.get("num_samples", 1) - 1]
  
      super().__init__(
          info,
          preload,
          filenames=[input_fname],
          raw_extras=[header_info],
          last_samps=last_samps,
          orig_format="single",
          verbose=verbose,
      )
  
      if add_head_trans:
          n_hpis = 0
          for d in info["hpi_subsystem"]["hpi_coils"]:
              if d["event_bits"] == [256]:
                  n_hpis += 1
          if n_hpis < 3:
              warn(
                  "%d HPIs active. At least 3 needed to perform"
                  % n_hpis
                  + "head localization\n *NO* head localization performed"
              )
          else:
              # Localized HPIs using the 1st 250 milliseconds of data.
              with info._unlock():
                  info["hpi_results"] = [
                      dict(
                          dig_points=[
                              dict(
                                  r=np.zeros(3),
                                  coord_frame=FIFF.FIFFV_COORD_DEVICE,
                                  ident=ii + 1,
                              )
                              for ii in range(n_hpis)
                          ],
                          coord_trans=Transform("meg", "head"),
                      )
                  ]
              coil_amplitudes = compute_chpi_amplitudes(
                  self,
                  tmin=0,
                  tmax=0.25,
                  t_window=0.25,
                  t_step_min=0.25,
              )
              assert len(coil_amplitudes["times"]) == 1
              coil_locs = compute_chpi_locs(self.info, coil_amplitudes)
              with info._unlock():
                  info["hpi_results"] = None
              hpi_g = coil_locs["gofs"][0]
              hpi_dev = coil_locs["rrs"][0]
  
              # only use HPI coils with localizaton goodness_of_fit > 0.98
              bad_idx = []
              for i, g in enumerate(hpi_g):
                  msg = "HPI coil %d - location goodness of fit (%0.3f)"
                  if g < 0.98:
                      bad_idx.append(i)
                      msg += " *Removed from coregistration*"
                  logger.info(msg % (i + 1, g))
              hpi_dev = np.delete(hpi_dev, bad_idx, axis=0)
              hpi_g = np.delete(hpi_g, bad_idx, axis=0)
  
              if pos_fname is not None:
                  # Digitized HPI points are needed.
                  hpi_head = np.array(
                      [
                          d["r"]
                          for d in self.info.get("dig", [])
                          if d["kind"] == FIFF.FIFFV_POINT_HPI
                      ]
                  )
  
                  if len(hpi_head) != len(hpi_dev):
                      mesg = (
                          "number of digitized (%d) and "
                          + "active (%d) HPI coils are "
                          + "not the same."
                      )
                      raise RuntimeError(
                          mesg % (len(hpi_head), len(hpi_dev))
                      )
  
                  # compute initial head to dev transform and hpi ordering
                  (
                      head_to_dev_t,
                      order,
                      trans_g,
                  ) = _fit_coil_order_dev_head_trans(hpi_dev, hpi_head)
  
                  # set the device to head transform
                  self.info["dev_head_t"] = Transform(
                      FIFF.FIFFV_COORD_DEVICE,
                      FIFF.FIFFV_COORD_HEAD,
                      head_to_dev_t,
                  )
  
                  # add hpi_meg_dev to dig...
                  for idx, point in enumerate(hpi_dev):
                      d = {
                          "r": point,
                          "ident": idx + 1,
                          "kind": FIFF.FIFFV_POINT_HPI,
                          "coord_frame": FIFF.FIFFV_COORD_DEVICE,
                      }
                      self.info["dig"].append(DigPoint(d))
  
                  dig_dists = cdist(hpi_head[order], hpi_head[order])
                  dev_dists = cdist(hpi_dev, hpi_dev)
                  tmp_dists = np.abs(dig_dists - dev_dists)
                  dist_limit = tmp_dists.max() * 1.1
  
                  msg = "HPI-Dig corrregsitration\n"
                  msg += "\tGOF : %0.3f\n" % trans_g
                  msg += "\tMax Coil Error : %0.3f cm\n" % (
                      100 * tmp_dists.max()
                  )
                  logger.info(msg)
  
              else:
                  logger.info("Assuming Cardinal HPIs")
                  nas = hpi_dev[0]
                  lpa = hpi_dev[2]
                  rpa = hpi_dev[1]
                  t = get_ras_to_neuromag_trans(nas, lpa, rpa)
                  with self.info._unlock():
                      self.info["dev_head_t"] = Transform(
                          FIFF.FIFFV_COORD_DEVICE,
                          FIFF.FIFFV_COORD_HEAD,
                          t,
                      )
  
                  # transform fiducial points
                  nas = apply_trans(t, nas)
                  lpa = apply_trans(t, lpa)
                  rpa = apply_trans(t, rpa)
  
                  hpi = apply_trans(self.info["dev_head_t"], hpi_dev)
                  with self.info._unlock():
                      self.info["dig"] = _make_dig_points(
                          nasion=nas, lpa=lpa, rpa=rpa, hpi=hpi
                      )
                  order = np.array([0, 1, 2])
                  dist_limit = 0.005
  
              # fill in hpi_results
              hpi_result = dict()
  
              # add HPI points in device coords...
              dig = []
              for idx, point in enumerate(hpi_dev):
                  dig.append(
                      {
                          "r": point,
                          "ident": idx + 1,
                          "kind": FIFF.FIFFV_POINT_HPI,
                          "coord_frame": FIFF.FIFFV_COORD_DEVICE,
                      }
                  )
              hpi_result["dig_points"] = dig
  
              # attach Transform
              hpi_result["coord_trans"] = self.info["dev_head_t"]
  
              # 1 based indexing
              hpi_result["order"] = order + 1
              hpi_result["used"] = np.arange(3) + 1
              hpi_result["dist_limit"] = dist_limit
              hpi_result["good_limit"] = 0.98
  
              # Warn for large discrepancies between digitized and fit
              # cHPI locations
              if hpi_result["dist_limit"] > 0.005:
                  warn(
                      "Large difference between digitized geometry"
                      + " and HPI geometry. Max coil to coil difference"
                      + " is %0.2f cm\n" % (100.0 * tmp_dists.max())
                      + "beware of *POOR* head localization"
                  )
  
              # store it
              with self.info._unlock():
                  self.info["hpi_results"] = [hpi_result]
  
file_path: mne-python/mne/io/artemis123/artemis123.py
imports: import calendar
  import datetime
  import os.path
  import numpy
  from scipy.spatial.distance import cdist
  from ..._fiff._digitization import DigPoint, _make_dig_points
  from ..._fiff.constants import FIFF
  from ..._fiff.meas_info import _empty_info
  from ..._fiff.utils import _read_segments_file
  from ...transforms import Transform, apply_trans, get_ras_to_neuromag_trans
  from ...utils import _check_fname, logger, verbose, warn
  from ..base import BaseRaw
  from .utils import _load_mne_locs, _read_pos
label_desc: Use image node_id 1 to create a new RawArtemis123 object from inherited base classes: BaseRaw with example: obj = RawArtemis123(input_fname, preload, verbose, pos_fname, add_head_trans)