docs: def sites_extract(site_file='sites.txt', directions_file='directions.xls',
                    intensity_file='intensity.xls', info_file='site_info.xls',
                    output_dir_path='.', input_dir_path='', latex=False):
      """
      Extracts directional and/or intensity data from a MagIC 3.0 format sites.txt file.
      Default output format is an Excel file.
      Optional latex format longtable file which can be uploaded to Overleaf or
      typeset with latex on your own computer.
  
      Parameters
      ___________
      site_file : str
           input file name
      directions_file : str
            output file name for directional data
      intensity_file : str
            output file name for intensity data
      site_info : str
            output file name for site information (lat, lon, location, age....)
      output_dir_path : str
            path for output files
      input_dir_path : str
            path for intput file if different from output_dir_path (default is same)
      latex : boolean
             if True, output file should be latex formatted table with a .tex ending
  
      Return :
          [True,False], error type : True if successful
  
      Effects :
          writes Excel or LaTeX formatted tables for use in publications
      """
      # initialize outfile names
      input_dir_path, output_dir_path = pmag.fix_directories(input_dir_path, output_dir_path)
      try:
          fname = pmag.resolve_file_name(site_file, input_dir_path)
      except IOError:
          print("bad site file name")
          return False, "bad site file name"
      sites_df = pd.read_csv(fname, sep='\t', header=1)
      dir_df = map_magic.convert_site_dm3_table_directions(sites_df)
      dir_file = pmag.resolve_file_name(directions_file, output_dir_path)
      if len(dir_df):
          if latex:
              if dir_file.endswith('.xls'):
                  dir_file = dir_file[:-4] + ".tex"
              directions_out = open(dir_file, 'w+', errors="backslashreplace")
              directions_out.write('\documentclass{article}\n')
              directions_out.write('\\usepackage{booktabs}\n')
              directions_out.write('\\usepackage{longtable}\n')
              directions_out.write('\\begin{document}')
              directions_out.write(dir_df.to_latex(
                  index=False, longtable=True, multicolumn=False))
              directions_out.write('\end{document}\n')
              directions_out.close()
          else:
              dir_df.to_excel(dir_file, index=False)
      else:
          print("No directional data for ouput.")
          dir_file = None
      intensity_file = pmag.resolve_file_name(intensity_file, output_dir_path)
      int_df = map_magic.convert_site_dm3_table_intensity(sites_df)
      if len(int_df):
          if latex:
              if intensity_file.endswith('.xls'):
                  intensity_file = intensity_file[:-4] + ".tex"
              intensities_out = open(intensity_file, 'w+',
                                     errors="backslashreplace")
              intensities_out.write('\documentclass{article}\n')
              intensities_out.write('\\usepackage{booktabs}\n')
              intensities_out.write('\\usepackage{longtable}\n')
              intensities_out.write('\\begin{document}')
              intensities_out.write(int_df.to_latex(
                  index=False, longtable=True, multicolumn=False))
              intensities_out.write('\end{document}\n')
              intensities_out.close()
          else:
              int_df.to_excel(intensity_file, index=False)
      else:
          print("No intensity data for ouput.")
          intensity_file = None
  # site info
      nfo_df = sites_df.dropna(subset=['lat', 'lon'])  # delete blank locations
      if len(nfo_df) > 0:
          SiteCols = ["Site", "Location", "Lat. (N)", "Long. (E)"]
          info_file = pmag.resolve_file_name(info_file, output_dir_path)
          age_cols = ['age', 'age_sigma', 'age_unit']
          for col in age_cols:
              if col not in nfo_df:
                  nfo_df[col] = None
          test_age = nfo_df.dropna(subset=['age', 'age_sigma', 'age_unit'])
          if len(test_age) > 0:
              SiteCols.append("Age ")
              SiteCols.append("Age sigma")
              SiteCols.append("Units")
              nfo_df = nfo_df[['site', 'location', 'lat',
                               'lon', 'age', 'age_sigma', 'age_unit']]
          else:
              nfo_df = nfo_df[['site', 'location', 'lat', 'lon']]
          nfo_df.drop_duplicates(inplace=True)
          nfo_df.columns = SiteCols
          nfo_df.fillna(value='', inplace=True)
          if latex:
              if info_file.endswith('.xls'):
                  info_file = info_file[:-4] + ".tex"
              info_out = open(info_file, 'w+', errors="backslashreplace")
              info_out.write('\documentclass{article}\n')
              info_out.write('\\usepackage{booktabs}\n')
              info_out.write('\\usepackage{longtable}\n')
              info_out.write('\\begin{document}')
              info_out.write(nfo_df.to_latex(
                  index=False, longtable=True, multicolumn=False))
              info_out.write('\end{document}\n')
              info_out.close()
          else:
              nfo_df.to_excel(info_file, index=False)
      else:
          print("No location information  for ouput.")
          info_file = None
      return True, [fname for fname in [info_file, intensity_file, dir_file] if fname]