docs: def pmd(mag_file, dir_path=".", input_dir_path="",
          meas_file="measurements.txt", spec_file='specimens.txt',
          samp_file='samples.txt', site_file="sites.txt", loc_file="locations.txt",
          lat="", lon="", specnum=0, samp_con='1', location="unknown",
          noave=0, meth_code="LP-NO"):
      """
      converts PMD (Enkin)  format files to MagIC format files
  
      Parameters
      ----------
      mag_file : str
          input file name, required
      dir_path : str
          working directory, default "."
      input_dir_path : str
          input file directory IF different from dir_path, default ""
      spec_file : str
          output specimen file name, default "specimens.txt"
      samp_file: str
          output sample file name, default "samples.txt"
      site_file : str
          output site file name, default "sites.txt"
      loc_file : str
          output location file name, default "locations.txt"
      lat : float or str
          latitude, default ""
      lon : float or str
          longitude, default ""
      specnum : int
          number of characters to designate a specimen, default 0
      samp_con : str
          sample/site naming convention, default '1', see info below
      location : str
          location name, default "unknown"
      noave : bool
         do not average duplicate measurements, default False (so by default, DO average)
      meth_code : str
          default "LP-NO"
          e.g. [SO-MAG, SO-SUN, SO-SIGHT, ...]
  
      Returns
      ---------
      Tuple : (True or False indicating if conversion was sucessful, file name written)
  
  
      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
  
  
      """
      input_dir_path, output_dir_path = pmag.fix_directories(input_dir_path, dir_path)
      specnum = - int(specnum)
      samp_con = str(samp_con)
      version_num = pmag.get_version()
  
      if "4" in samp_con:
          if "-" not in samp_con:
              print(
                  "naming convention option [4] must be in form 4-Z where Z is an integer")
              return False, "naming convention option [4] must be in form 4-Z where Z is an integer"
          else:
              Z = samp_con.split("-")[1]
              samp_con = "4"
      elif "7" in samp_con:
          if "-" not in samp_con:
              print("option [7] must be in form 7-Z where Z is an integer")
              return False, "naming convention option [7] must be in form 7-Z where Z is an integer"
          else:
              Z = samp_con.split("-")[1]
              samp_con = "7"
      else:
          Z = 1
  
      # format variables
      mag_file = pmag.resolve_file_name(mag_file, input_dir_path)
      meas_file = pmag.resolve_file_name(meas_file, output_dir_path)
      spec_file = pmag.resolve_file_name(spec_file, output_dir_path)
      samp_file = pmag.resolve_file_name(samp_file, output_dir_path)
      site_file = pmag.resolve_file_name(site_file, output_dir_path)
  
      # parse data
      try:
          with open(mag_file, 'r') as f:
              data = f.readlines()
      except IOError:
          print('mag_file field is required option')
          return False, 'mag_file field is required option'
      comment = data[0]
      line = data[1].strip()
      line = line.replace("=", "= ")  # make finding orientations easier
      rec = line.split()  # read in sample orientation, etc.
      specimen = rec[0]
      SpecRecs, SampRecs, SiteRecs, LocRecs, MeasRecs = [], [], [], [], []
      SpecRec, SampRec, SiteRec, LocRec = {}, {}, {}, {}  # make a  sample record
      if specnum != 0:
          sample = rec[0][:specnum]
      else:
          sample = rec[0]
      if int(samp_con) < 6:
          site = pmag.parse_site(sample, samp_con, Z)
      else:
          if 'site' in list(SampRec.keys()):
              site = ErSampREc['site']
          if 'location' in list(SampRec.keys()):
              location = ErSampREc['location']
      az_ind = rec.index('a=')+1
      SampRec['sample'] = sample
      SampRec['description'] = comment.replace('\n', '').replace('\t', '')
      SampRec['azimuth'] = rec[az_ind]
      dip_ind = rec.index('b=')+1
      dip = -float(rec[dip_ind])
      SampRec['dip'] = '%7.1f' % (dip)
      strike_ind = rec.index('s=')+1
      SampRec['bed_dip_direction'] = '%7.1f' % (float(rec[strike_ind])+90.)
      bd_ind = rec.index('d=')+1
      SampRec['bed_dip'] = rec[bd_ind]
      v_ind = rec.index('v=')+1
      vol = rec[v_ind][:-3]
      date = rec[-2]
      time = rec[-1]
      SampRec['method_codes'] = meth_code
      SampRec['site'] = site
      SampRec['citations'] = 'This study'
      SampRec['method_codes'] = 'SO-NO'
  
      SpecRec['specimen'] = specimen
      SpecRec['sample'] = sample
      SpecRec['citations'] = 'This study'
  
      SiteRec['site'] = site
      SiteRec['location'] = location
      SiteRec['citations'] = 'This study'
      SiteRec['lat'] = lat
      SiteRec['lon'] = lon
  
      LocRec['location'] = location
      LocRec['citations'] = 'This study'
      LocRec['lat_n'] = lat
      LocRec['lat_s'] = lat
      LocRec['lon_e'] = lon
      LocRec['lon_w'] = lon
  
      SpecRecs.append(SpecRec)
      SampRecs.append(SampRec)
      SiteRecs.append(SiteRec)
      LocRecs.append(LocRec)
      for k in range(3, len(data)):  # read in data
          line = data[k]
          rec = line.split()
          if len(rec) > 1:  # skip blank lines at bottom
              MeasRec = {}
              MeasRec['description'] = 'Date: '+date+' '+time
              MeasRec["citations"] = "This study"
              MeasRec['software_packages'] = version_num
              MeasRec["treat_temp"] = '%8.3e' % (273)  # room temp in kelvin
              MeasRec["meas_temp"] = '%8.3e' % (273)  # room temp in kelvin
              MeasRec["quality"] = 'g'
              MeasRec["standard"] = 'u'
              MeasRec["treat_step_num"] = 0
              MeasRec["specimen"] = specimen
              if rec[0] == 'NRM':
                  meas_type = "LT-NO"
              elif rec[0][0] == 'M' or rec[0][0] == 'H':
                  meas_type = "LT-AF-Z"
              elif rec[0][0] == 'T':
                  meas_type = "LT-T-Z"
              else:
                  print("measurement type unknown")
                  return False, "measurement type unknown"
              X = [float(rec[1]), float(rec[2]), float(rec[3])]
              Vec = pmag.cart2dir(X)
              MeasRec["magn_moment"] = '%10.3e' % (Vec[2])  # Am^2
              MeasRec["magn_volume"] = rec[4]  # A/m
              MeasRec["dir_dec"] = '%7.1f' % (Vec[0])
              MeasRec["dir_inc"] = '%7.1f' % (Vec[1])
              MeasRec["treat_ac_field"] = '0'
              if meas_type != 'LT-NO':
                  treat = float(rec[0][1:])
              else:
                  treat = 0
              if meas_type == "LT-AF-Z":
                  MeasRec["treat_ac_field"] = '%8.3e' % (
                      treat*1e-3)  # convert from mT to tesla
              elif meas_type == "LT-T-Z":
                  MeasRec["treat_temp"] = '%8.3e' % (
                      treat+273.)  # temp in kelvin
              MeasRec['method_codes'] = meas_type
              MeasRecs.append(MeasRec)
  
      con = cb.Contribution(output_dir_path, read_tables=[])
  
      con.add_magic_table_from_data(dtype='specimens', data=SpecRecs)
      con.add_magic_table_from_data(dtype='samples', data=SampRecs)
      con.add_magic_table_from_data(dtype='sites', data=SiteRecs)
      con.add_magic_table_from_data(dtype='locations', data=LocRecs)
      MeasOuts = pmag.measurements_methods3(MeasRecs, noave)
      con.add_magic_table_from_data(dtype='measurements', data=MeasOuts)
  
      con.tables['specimens'].write_magic_file(custom_name=spec_file,dir_path=dir_path)
      con.tables['samples'].write_magic_file(custom_name=samp_file,dir_path=dir_path)
      con.tables['sites'].write_magic_file(custom_name=site_file,dir_path=dir_path)
      con.tables['locations'].write_magic_file(custom_name=loc_file,dir_path=dir_path)
      con.tables['measurements'].write_magic_file(custom_name=meas_file,dir_path=dir_path)
  
      return True, meas_file