docs: def bgc(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', append=False,
          location="unknown", site="", samp_con='1', specnum=0,
          meth_code="LP-NO", volume=12, user="", timezone='US/Pacific', noave=False):
  
      """
      Convert BGC format file to MagIC file(s)
  
      Parameters
      ----------
      mag_file : str
          input file name
      dir_path : str
          working directory, default "."
      input_dir_path : str
          input file directory IF different from dir_path, default ""
      meas_file : str
          output measurement file name, default "measurements.txt"
      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"
      append : bool
          append output files to existing files instead of overwrite, default False
      location : str
          location name, default "unknown"
      site : str
          site name, default ""
      samp_con : str
          sample/site naming convention, default '1', see info below
      specnum : int
          number of characters to designate a specimen, default 0
      meth_code : str
          orientation method codes, default "LP-NO"
          e.g. [SO-MAG, SO-SUN, SO-SIGHT, ...]
      volume : float
          volume in ccs, default 12.
      user : str
          user name, default ""
      timezone : str
          timezone in pytz library format, default "US/Pacific"
          list of timezones can be found at http://pytz.sourceforge.net/
      noave : bool
         do not average duplicate measurements, default False (so by default, DO average)
  
      Returns
      ---------
      Tuple : (True or False indicating if conversion was sucessful, meas_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 same as sample
          [6] site is entered under a separate column -- NOT CURRENTLY SUPPORTED
          [7-Z] [XXXX]YYY:  XXXX is site designation with Z characters with sample name XXXXYYYY
  
      """
  
      version_num = pmag.get_version()
      input_dir_path, output_dir_path = pmag.fix_directories(input_dir_path, dir_path)
      samp_con = str(samp_con)
      specnum = - int(specnum)
      volume *= 1e-6  # convert cc to m^3
  
      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 = int(samp_con.split("-")[1])
              samp_con = "4"
      if "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, "option [7] must be in form 7-Z where Z is an integer"
          else:
              Z = int(samp_con.split("-")[1])
              samp_con = "7"
      else:
          Z = 1
  
      # format variables
      mag_file = os.path.join(input_dir_path, mag_file)
      if not os.path.isfile(mag_file):
          print("%s is not a BGC file" % mag_file)
          return False, 'You must provide a BCG format file'
  
      # Open up the BGC file and read the header information
      print('mag_file in bgc_magic', mag_file)
      pre_data = open(mag_file, 'r')
      line = pre_data.readline()
      line_items = line.split(' ')
      specimen = line_items[2]
      specimen = specimen.replace('\n', '')
      line = pre_data.readline()
      line = pre_data.readline()
      line_items = line.split('\t')
      azimuth = float(line_items[1])
      dip = float(line_items[2])
      bed_dip = line_items[3]
      sample_bed_azimuth = line_items[4]
      lon = line_items[5]
      lat = line_items[6]
      tmp_volume = line_items[7]
      if tmp_volume != 0.0:
          volume = float(tmp_volume) * 1e-6
      pre_data.close()
  
      data = pd.read_csv(mag_file, sep='\t', header=3, index_col=False)
  
      cart = np.array([data['X'], data['Y'], data['Z']]).transpose()
      direction = pmag.cart2dir(cart).transpose()
  
      data['dir_dec'] = direction[0]
      data['dir_inc'] = direction[1]
      # the data are in EMU - this converts to Am^2
      data['magn_moment'] = direction[2] / 1000
      data['magn_volume'] = (direction[2] / 1000) / \
          volume  # EMU  - data converted to A/m
  
      # Configure the magic_measurements table
      MeasRecs, SpecRecs, SampRecs, SiteRecs, LocRecs = [], [], [], [], []
      for rowNum, row in data.iterrows():
          MeasRec, SpecRec, SampRec, SiteRec, LocRec = {}, {}, {}, {}, {}
  
          if specnum != 0:
              sample = specimen[:specnum]
          else:
              sample = specimen
          if site == '':
              site = pmag.parse_site(sample, samp_con, Z)
  
          if specimen != "" and specimen not in [x['specimen'] if 'specimen' in list(x.keys()) else "" for x in SpecRecs]:
              SpecRec['specimen'] = specimen
              SpecRec['sample'] = sample
              SpecRec['volume'] = volume
              SpecRec['analysts'] = user
              SpecRec['citations'] = 'This study'
              SpecRecs.append(SpecRec)
          if sample != "" and sample not in [x['sample'] if 'sample' in list(x.keys()) else "" for x in SampRecs]:
              SampRec['sample'] = sample
              SampRec['site'] = site
              SampRec['azimuth'] = azimuth
              SampRec['dip'] = dip
              SampRec['bed_dip_direction'] = sample_bed_azimuth
              SampRec['bed_dip'] = bed_dip
              SampRec['method_codes'] = meth_code
              SampRec['analysts'] = user
              SampRec['citations'] = 'This study'
              SampRecs.append(SampRec)
          if site != "" and site not in [x['site'] if 'site' in list(x.keys()) else "" for x in SiteRecs]:
              SiteRec['site'] = site
              SiteRec['location'] = location
              SiteRec['lat'] = lat
              SiteRec['lon'] = lon
              SiteRec['analysts'] = user
              SiteRec['citations'] = 'This study'
              SiteRecs.append(SiteRec)
          if location != "" and location not in [x['location'] if 'location' in list(x.keys()) else "" for x in LocRecs]:
              LocRec['location'] = location
              LocRec['analysts'] = user
              LocRec['citations'] = 'This study'
              LocRec['lat_n'] = lat
              LocRec['lon_e'] = lon
              LocRec['lat_s'] = lat
              LocRec['lon_w'] = lon
              LocRecs.append(LocRec)
  
          MeasRec['description'] = 'Date: ' + \
              str(row['Date']) + ' Time: ' + str(row['Time'])
          if '.' in row['Date']:
              datelist = row['Date'].split('.')
          elif '/' in row['Date']:
              datelist = row['Date'].split('/')
          elif '-' in row['Date']:
              datelist = row['Date'].split('-')
          else:
              print(
                  "unrecogized date formating on one of the measurement entries for specimen %s" % specimen)
              datelist = ['', '', '']
          if ':' in row['Time']:
              timelist = row['Time'].split(':')
          else:
              print(
                  "unrecogized time formating on one of the measurement entries for specimen %s" % specimen)
              timelist = ['', '', '']
          datelist[2] = '19' + \
              datelist[2] if len(datelist[2]) <= 2 else datelist[2]
          dt = ":".join([datelist[1], datelist[0], datelist[2],
                         timelist[0], timelist[1], timelist[2]])
          local = pytz.timezone(timezone)
          naive = datetime.datetime.strptime(dt, "%m:%d:%Y:%H:%M:%S")
          local_dt = local.localize(naive, is_dst=None)
          utc_dt = local_dt.astimezone(pytz.utc)
          timestamp = utc_dt.strftime("%Y-%m-%dT%H:%M:%S")+"Z"
          MeasRec["timestamp"] = timestamp
          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"] = rowNum
          MeasRec["specimen"] = specimen
          MeasRec["treat_ac_field"] = '0'
          if row['DM Val'] == '0':
              meas_type = "LT-NO"
          elif int(row['DM Type']) > 0.0:
              meas_type = "LT-AF-Z"
              treat = float(row['DM Val'])
              MeasRec["treat_ac_field"] = '%8.3e' % (
                  treat*1e-3)  # convert from mT to tesla
          elif int(row['DM Type']) == -1:
              meas_type = "LT-T-Z"
              treat = float(row['DM Val'])
              MeasRec["treat_temp"] = '%8.3e' % (treat+273.)  # temp in kelvin
          else:
              print("measurement type unknown:",
                    row['DM Type'], " in row ", rowNum)
          MeasRec["magn_moment"] = str(row['magn_moment'])
          MeasRec["magn_volume"] = str(row['magn_volume'])
          MeasRec["dir_dec"] = str(row['dir_dec'])
          MeasRec["dir_inc"] = str(row['dir_inc'])
          MeasRec['method_codes'] = meas_type
          MeasRec['dir_csd'] = '0.0'  # added due to magic.write error
          MeasRec['meas_n_orient'] = '1'  # added due to magic.write error
          MeasRecs.append(MeasRec.copy())
  
      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.write_table_to_file('specimens', custom_name=spec_file, append=append)
      con.write_table_to_file('samples', custom_name=samp_file, append=append)
      con.write_table_to_file('sites', custom_name=site_file, append=append)
      con.write_table_to_file('locations', custom_name=loc_file, append=append)
      meas_file = con.write_table_to_file(
          'measurements', custom_name=meas_file, append=append)
  
      return True, meas_file