docs: def convert_directory_2_to_3(meas_fname="magic_measurements.txt", input_dir=".",
                               output_dir=".", meas_only=False, data_model=None):
      """
      Convert 2.0 measurements file into 3.0 measurements file.
      Merge and convert specimen, sample, site, and location data.
      Also translates criteria data.
  
      Parameters
      ----------
      meas_name : name of measurement file (do not include full path,
          default is "magic_measurements.txt")
      input_dir : name of input directory (default is ".")
      output_dir : name of output directory (default is ".")
      meas_only : boolean, convert only measurement data (default is False)
      data_model : data_model3.DataModel object (default is None)
  
      Returns
      ---------
      NewMeas : 3.0 measurements data (output of pmag.convert_items)
      upgraded : list of files successfully upgraded to 3.0
      no_upgrade: list of 2.5 files not upgraded to 3.0
      """
      convert = {'specimens': map_magic.spec_magic2_2_magic3_map,
                 'samples': map_magic.samp_magic2_2_magic3_map,
                 'sites': map_magic.site_magic2_2_magic3_map,
                 'locations': map_magic.loc_magic2_2_magic3_map,
                 'ages': map_magic.age_magic2_2_magic3_map}
      full_name = os.path.join(input_dir, meas_fname)
      if not os.path.exists(full_name):
          print("-W- {} is not a file".format(full_name))
          return False, False, False
      # read in data model 2.5 measurements file
      data2, filetype = magic_read(full_name)
      # convert list of dicts to 3.0
      NewMeas = convert_items(data2, map_magic.meas_magic2_2_magic3_map)
      # write 3.0 output to file
      ofile = os.path.join(output_dir, 'measurements.txt')
      magic_write(ofile, NewMeas, 'measurements')
      upgraded = []
      if os.path.exists(ofile):
          print("-I- 3.0 format measurements file was successfully created: {}".format(ofile))
          upgraded.append("measurements.txt")
      else:
          print("-W- 3.0 format measurements file could not be created")
      #
      no_upgrade = []
      if not meas_only:
          # try to convert specimens, samples, sites, & locations
          for dtype in ['specimens', 'samples', 'sites', 'locations', 'ages']:
              mapping = convert[dtype]
              res = convert_and_combine_2_to_3(
                  dtype, mapping, input_dir, output_dir, data_model)
              if res:
                  upgraded.append(res)
          # try to upgrade criteria file
          if os.path.exists(os.path.join(input_dir, 'pmag_criteria.txt')):
              crit_file = convert_criteria_file_2_to_3(input_dir=input_dir,
                                                       output_dir=output_dir,
                                                       data_model=data_model)[0]
              if crit_file:
                  upgraded.append(crit_file)
              else:
                  no_upgrade.append("pmag_criteria.txt")
          # create list of all un-upgradeable files
          for fname in os.listdir(input_dir):
              if fname in ['measurements.txt', 'specimens.txt', 'samples.txt',
                           'sites.txt', 'locations.txt']:
                  continue
              elif 'rmag' in fname:
                  no_upgrade.append(fname)
              elif fname in ['pmag_results.txt', 'er_synthetics.txt', 'er_images.txt',
                             'er_plots.txt']:
                  no_upgrade.append(fname)
  
      return NewMeas, upgraded, no_upgrade