docs: def download_magic(infile, dir_path='.', input_dir_path='',
                     overwrite=False, print_progress=True,
                     data_model=3., separate_locs=False):
      """
      takes the name of a text file downloaded from the MagIC database and
      unpacks it into magic-formatted files. by default, download_magic assumes
      that you are doing everything in your current directory. if not, you may
      provide optional arguments dir_path (where you want the results to go) and
      input_dir_path (where the downloaded file is IF that location is different from
      dir_path).
  
      Parameters
      ----------
      infile : str
          MagIC-format file to unpack
      dir_path : str
          output directory (default ".")
      input_dir_path : str, default ""
          path for intput file if different from output_dir_path (default is same)
      overwrite: bool
          overwrite current directory (default False)
      print_progress: bool
          verbose output (default True)
      data_model : float
          MagIC data model 2.5 or 3 (default 3)
      separate_locs : bool
          create a separate directory for each location (Location_*)
          (default False)
      """
      if data_model == 2.5:
          method_col = "magic_method_codes"
      else:
          method_col = "method_codes"
  
      input_dir_path, dir_path = pmag.fix_directories(input_dir_path, dir_path)
      infile = pmag.resolve_file_name(infile, input_dir_path)
      # try to deal reasonably with unicode errors
      try:
          f = codecs.open(infile, 'r', "utf-8")
          infile = f.readlines()
      except UnicodeDecodeError:
          f = codecs.open(infile, 'r', "Latin-1")
          infile = f.readlines()
      f.close()
      File = []  # will contain all non-blank lines from downloaded file
      for line in infile:
          line = line.replace('\n', '')
          if line[0:4] == '>>>>' or len(line.strip()) > 0:  # skip blank lines
              File.append(line)
      LN = 0  # tracks our progress iterating through File
      type_list = []
      filenum = 0
      while LN < len(File) - 1:
          line = File[LN]
          if ">>>>" in line:
              LN += 1
              continue
          file_type = line.split('\t')[1]
          file_type = file_type.lower()
          if file_type[-1] == "\n":
              file_type = file_type[:-1]
          if print_progress == True:
              print('working on: ', repr(file_type))
          if file_type not in type_list:
              type_list.append(file_type)
          else:
              filenum += 1
          LN += 1
          line = File[LN]
          # skip empty tables
          if line == ">>>>>>>>>>":
              LN += 1
              continue
          keys = line.replace('\n', '').split('\t')
          if keys[0][0] == '.':
              keys = line.replace('\n', '').replace('.', '').split('\t')
              keys.append('RecNo')  # cludge for new MagIC download format
          LN += 1
          Recs = []
          while LN < len(File):
              line = File[LN]
              # finish up one file type and then break
              if ">>>>" in line and len(Recs) > 0:
                  if filenum == 0:
                      outfile = os.path.join(dir_path, file_type.strip() + '.txt')
                  else:
                      outfile = os.path.join(dir_path, file_type.strip() + '_' + str(filenum) + '.txt')
                  NewRecs = []
                  for rec in Recs:
                      if method_col in list(rec.keys()):
                          meths = rec[method_col].split(":")
                          if len(meths) > 0:
                              methods = ""
                              for meth in meths:
                                  methods = methods + meth.strip() + ":"  # get rid of nasty spaces!!!!!!
                              rec[method_col] = methods[:-1]
                      NewRecs.append(rec)
                  pmag.magic_write(outfile, Recs, file_type)
                  if print_progress == True:
                      print(file_type, " data put in ", outfile)
                  Recs = []
                  LN += 1
                  break
              # keep adding records of the same file type
              else:
                  rec = line.split('\t')
                  Rec = {}
                  if len(rec) == len(keys):
                      for k in range(len(rec)):
                          Rec[keys[k]] = rec[k]
                      Recs.append(Rec)
                  # in case of magic_search_results.txt, which has an extra
                  # column:
                  elif len(rec) - len(keys) == 1:
                      for k in range(len(rec))[:-1]:
                          Rec[keys[k]] = rec[k]
                      Recs.append(Rec)
                  elif len(rec) < len(keys):
                      for k in range(len(rec)):
                          Rec[keys[k]] = rec[k]
                      for k in range(len(rec), len(keys)):
                          Rec[keys[k]] = ""
                      Recs.append(Rec)
                  else:
                      print('WARNING:  problem in file with line: ')
                      print(line)
                      print('skipping....')
                  LN += 1
      if len(Recs) > 0:
          if filenum == 0:
              outfile = os.path.join(dir_path, file_type.strip() + '.txt')
          else:
              outfile = os.path.join(dir_path, file_type.strip() + '_' + str(filenum) + '.txt')
          NewRecs = []
          for rec in Recs:
              if method_col in list(rec.keys()):
                  meths = rec[method_col].split(":")
                  if len(meths) > 0:
                      methods = ""
                      for meth in meths:
                          methods = methods + meth.strip() + ":"  # get rid of nasty spaces!!!!!!
                      rec[method_col] = methods[:-1]
              NewRecs.append(rec)
          pmag.magic_write(outfile, Recs, file_type)
          if print_progress == True:
              print(file_type, " data put in ", outfile)
      # look through locations table and create separate directories for each
      # location
      if separate_locs:
          con = cb.Contribution(dir_path)
          con.propagate_location_to_measurements()
          con.propagate_name_down('location', 'samples')
          for dtype in con.tables:
              con.write_table_to_file(dtype)
          locs, locnum = [], 1
          if 'locations' in type_list:
              locs, file_type = pmag.magic_read(
                  os.path.join(dir_path, 'locations.txt'))
          if len(locs) > 0:  # at least one location
              # go through unique location names
              for loc_name in set([loc.get('location') for loc in locs]):
                  if print_progress == True:
                      print('location_' + str(locnum) + ": ", loc_name)
                  lpath = os.path.join(dir_path, 'Location_' + str(locnum))
                  locnum += 1
                  try:
                      os.mkdir(lpath)
                  except:
                      print('directory ', lpath,
                            ' already exists - overwriting everything: {}'.format(overwrite))
                      if not overwrite:
                          print("-W- download_magic encountered a duplicate subdirectory ({}) and could not finish.\nRerun with overwrite=True, or unpack this file in a different directory.".format(lpath))
                          return False
                  for f in type_list:
                      fname = os.path.join(dir_path, f + '.txt')
                      if print_progress == True:
                          print('unpacking: ', fname)
                      recs, file_type = pmag.magic_read(fname)
                      if print_progress == True:
                          print(len(recs), ' read in')
                      lrecs = pmag.get_dictitem(recs, 'location', loc_name, 'T')
                      if len(lrecs) > 0:
                          outfile_name = os.path.join(lpath, f + ".txt")
                          pmag.magic_write(outfile_name, lrecs, file_type)
                          if print_progress == True:
                              print(len(lrecs), ' stored in ', outfile_name)
      return True