docs: def convert_criteria_file_2_to_3(fname="pmag_criteria.txt", input_dir=".",
                                   output_dir=".", data_model=None):
      """
      Convert a criteria file from 2.5 to 3.0 format and write it out to file
  
      Parameters
      ----------
      fname : string of filename (default "pmag_criteria.txt")
      input_dir : string of input directory (default ".")
      output_dir : string of output directory (default ".")
      data_model : data_model.DataModel object (default None)
  
      Returns
      ---------
      outfile : string output criteria filename, or False
      crit_container : cb.MagicDataFrame with 3.0 criteria table
      """
      # get criteria from infile
      fname = os.path.join(input_dir, fname)
      if not os.path.exists(fname):
          return False, None
      orig_crit, warnings = read_criteria_from_file(fname, initialize_acceptance_criteria(),
                                                    data_model=2, return_warnings=True)
      converted_crit = {}
      # get data model including criteria map
      if not data_model:
          from . import data_model3 as dm3
          DM = dm3.DataModel()
      else:
          DM = data_model
      crit_map = DM.crit_map
      # drop all empty mappings
      stripped_crit_map = crit_map.dropna(axis='rows')
      # go through criteria and get 3.0 name and criterion_operation
      for crit in orig_crit:
          if orig_crit[crit]['value'] in [-999, '-999', -999.]:
              continue
          if crit in stripped_crit_map.index:
              criterion_operation = stripped_crit_map.loc[crit]['criteria_map']['criterion_operation']
              table_col = stripped_crit_map.loc[crit]['criteria_map']['table_column']
              orig_crit[crit]['criterion_operation'] = criterion_operation
              converted_crit[table_col] = orig_crit[crit]
          else:
              print('-W- Could not convert {} to 3.0, skipping'.format(crit))
      # switch axes
      converted_df = pd.DataFrame(converted_crit).transpose()
      # name the index
      converted_df.index.name = "table_column"
      # rename columns to 3.0 values
      # 'category' --> criterion (uses defaults from initalize_default_criteria)
      # 'pmag_criteria_code' --> criterion (uses what's actually in the translated file)
      converted_df.rename(columns={'pmag_criteria_code': 'criterion', 'er_citation_names': 'citations',
                                   'criteria_definition': 'description', 'value': 'criterion_value'},
                          inplace=True)
      # drop unused columns
      valid_cols = DM.dm['criteria'].index
      drop_cols = set(converted_df.columns) - set(valid_cols)
      converted_df.drop(drop_cols, axis='columns', inplace=True)
      # move 'table_column' from being the index to being a column
      converted_df['table_column'] = converted_df.index
      crit_container = cb.MagicDataFrame(dtype='criteria', df=converted_df)
      crit_container.write_magic_file(dir_path=output_dir)
      return "criteria.txt", crit_container