docs: def s_magic(sfile, anisfile="specimens.txt", dir_path=".", atype="AMS",
              coord_type="s", sigma=False, samp_con="1", specnum=0,
              location="unknown", spec="unknown", sitename="unknown",
              user="", data_model_num=3, name_in_file=False, input_dir_path=""):
      """
      converts .s format data to measurements  format.
  
      Parameters
      ----------
      sfile : str
         .s format file, required
      anisfile : str
          specimen filename, default 'specimens.txt'
      dir_path : str
          output directory, default "."
      atype : str
          anisotropy type (AMS, AARM, ATRM, default AMS)
      coord_type : str
         coordinate system ('s' for specimen, 't' for tilt-corrected,
         or 'g' for geographic, default 's')
      sigma : bool
         if True, last column has sigma, default False
      samp_con : str
          sample/site naming convention, default '1', see info below
      specnum : int
          number of characters to designate a specimen, default 0
      location : str
          location name, default "unknown"
      spec : str
          specimen name, default "unknown"
      sitename : str
          site name, default "unknown"
      user : str
          user name, default ""
      data_model_num : int
          MagIC data model 2 or 3, default 3
      name_in_file : bool
          first entry of each line is specimen name, default False
      input_dir_path : input directory path IF different from dir_path, default ""
  
      Returns
      ---------
      Tuple : (True or False indicating if conversion was sucessful, meas_file name written)
  
  
      Input format
      --------
          X11,X22,X33,X12,X23,X13  (.s format file)
          X11,X22,X33,X12,X23,X13,sigma (.s format file with -sig option)
          SID, X11,X22,X33,X12,X23,X13  (.s format file with -n option)
  
      Info
      --------
      Sample naming convention:
          [1] XXXXY: where XXXX is an arbitrary length site designation and Y
              is the single character sample designation.  e.g., TG001a is the
              first sample from site TG001.    [default]
          [2] XXXX-YY: YY sample from site XXXX (XXX, YY of arbitary length)
          [3] XXXX.YY: YY sample from site XXXX (XXX, YY of arbitary length)
          [4-Z] XXXX[YYY]:  YYY is sample designation with Z characters from site XXX
          [5] site name = sample name
          [6] site name entered in site_name column in the orient.txt format input file  -- NOT CURRENTLY SUPPORTED
          [7-Z] [XXX]YYY:  XXX is site designation with Z characters from samples  XXXYYY
  
  
      """
      con, Z = "", 1
      if samp_con:
          samp_con = str(samp_con)
          if "4" in samp_con:
              if "-" not in samp_con:
                  print("option [4] must be in form 4-Z where Z is an integer")
                  return False, "option [4] must be in form 4-Z where Z is an integer"
              else:
                  Z = samp_con.split("-")[1]
                  samp_con = "4"
          if samp_con == '6':
              print("option [6] is not currently supported")
              return
      else:
          samp_con = con
  
  
      coord_dict = {'s': '-1', 't': '100', 'g': '0'}
      coord = coord_dict.get(coord_type, '-1')
      specnum = -specnum
  
      if data_model_num == 2:
          specimen_col = "er_specimen_name"
          sample_col = "er_sample_name"
          site_col = "er_site_name"
          loc_col = "er_location_name"
          citation_col = "er_citation_names"
          analyst_col = "er_analyst_mail_names"
          aniso_type_col = "anisotropy_type"
          experiment_col = "magic_experiment_names"
          sigma_col = "anisotropy_sigma"
          unit_col = "anisotropy_unit"
          tilt_corr_col = "anisotropy_tilt_correction"
          method_col = "magic_method_codes"
          outfile_type = "rmag_anisotropy"
      else:
          specimen_col = "specimen"
          sample_col = "sample"
          site_col = "site"
          loc_col = "location"
          citation_col = "citations"
          analyst_col = "analysts"
          aniso_type_col = "aniso_type"
          experiment_col = "experiments"
          sigma_col = "aniso_s_sigma"
          unit_col = "aniso_s_unit"
          tilt_corr_col = "aniso_tilt_correction"
          method_col = "method_codes"
          outfile_type = "specimens"
      # get down to bidness
      input_dir_path, dir_path = pmag.fix_directories(input_dir_path, dir_path)
      sfile = pmag.resolve_file_name(sfile, input_dir_path)
      anisfile = pmag.resolve_file_name(anisfile, dir_path)
      try:
          with open(sfile, 'r') as f:
              lines = f.readlines()
      except FileNotFoundError:
          return False, "No such file: {}".format(sfile)
      AnisRecs = []
      citation = "This study"
      # read in data
      for line in lines:
          AnisRec = {}
          rec = line.split()
          if name_in_file:
              k = 1
              spec = rec[0]
          else:
              k = 0
          trace = float(rec[k])+float(rec[k+1])+float(rec[k+2])
          s1 = '%10.9e' % (float(rec[k]) / trace)
          s2 = '%10.9e' % (float(rec[k+1]) / trace)
          s3 = '%10.9e' % (float(rec[k+2]) / trace)
          s4 = '%10.9e' % (float(rec[k+3]) / trace)
          s5 = '%10.9e' % (float(rec[k+4]) / trace)
          s6 = '%10.9e' % (float(rec[k+5]) / trace)
          AnisRec[citation_col] = citation
          AnisRec[specimen_col] = spec
          if specnum != 0:
              AnisRec[sample_col] = spec[:specnum]
          else:
              AnisRec[sample_col] = spec
          # if samp_con == "6":
          #    for samp in Samps:
          #        if samp['er_sample_name'] == AnisRec["er_sample_name"]:
          #            sitename = samp['er_site_name']
          #            location = samp['er_location_name']
          if samp_con != "":
              sitename = pmag.parse_site(AnisRec[sample_col], samp_con, Z)
          AnisRec[loc_col] = location
          AnisRec[site_col] = sitename
          AnisRec[analyst_col] = user
          if atype == 'AMS':
              AnisRec[aniso_type_col] = "AMS"
              AnisRec[experiment_col] = spec+":LP-X"
          else:
              AnisRec[aniso_type_col] = atype
              AnisRec[experiment_col] = spec+":LP-"+atype
          if data_model_num != 3:
              AnisRec["anisotropy_s1"] = s1
              AnisRec["anisotropy_s2"] = s2
              AnisRec["anisotropy_s3"] = s3
              AnisRec["anisotropy_s4"] = s4
              AnisRec["anisotropy_s5"] = s5
              AnisRec["anisotropy_s6"] = s6
          else:
              AnisRec['aniso_s'] = ":".join(
                  [str(s) for s in [s1, s2, s3, s4, s5, s6]])
          if sigma:
              AnisRec[sigma_col] = '%10.8e' % (
                  float(rec[k+6]) / trace)
              AnisRec[unit_col] = 'SI'
              AnisRec[tilt_corr_col] = coord
              AnisRec[method_col] = 'LP-' + atype
          AnisRecs.append(AnisRec)
      pmag.magic_write(anisfile, AnisRecs, outfile_type)
      print('data saved in ', anisfile)
      # try to extract location/site/sample info into tables
      con = cb.Contribution(dir_path, custom_filenames={"specimens": anisfile})
      con.propagate_all_tables_info()
      for table in con.tables:
          if table in ['samples', 'sites', 'locations']:
              # add in location name by hand
              if table == 'sites':
                  con.tables['sites'].df['location'] = location
              con.write_table_to_file(table)
      return True, anisfile