docs: def read_criteria_from_file(path, acceptance_criteria, **kwargs):
      '''
      Read accceptance criteria from magic criteria file
      # old format:
      multiple lines.  pmag_criteria_code defines the type of criteria
  
      to deal with old format this function reads all the lines and ignore empty cells.
      i.e., the program assumes that in each column there is only one value (in one of the lines)
  
      special case in the old format:
          specimen_dang has a value and pmag_criteria_code is IE-specimen.
          The program assumes that the user means specimen_int_dang
      # New format for thellier_gui and demag_gui:
      one long line. pmag_criteria_code=ACCEPT
  
      path is the full path to the criteria file
  
      the function takes exiting acceptance_criteria
      and updtate it with criteria from file
  
      output:
      acceptance_criteria={}
      acceptance_criteria[MagIC Variable Names]={}
      acceptance_criteria[MagIC Variable Names]['value']:
          a number for acceptance criteria value
          -999 for N/A
          1/0 for True/False or Good/Bad
      acceptance_criteria[MagIC Variable Names]['threshold_type']:
          "low":  lower cutoff value i.e. crit>=value pass criteria
          "high": high cutoff value i.e. crit<=value pass criteria
          [string1,string2,....]: for flags
      acceptance_criteria[MagIC Variable Names]['decimal_points']:number of decimal points in rounding
              (this is used in displaying criteria in the dialog box)
  
      '''
      warnings = []
      acceptance_criteria_list = list(acceptance_criteria.keys())
      if 'data_model' in list(kwargs.keys()) and kwargs['data_model'] == 3:
          crit_data = acceptance_criteria  # data already read in
      else:
          crit_data, file_type = magic_read(path)
          if 'criteria' not in file_type:
              if 'empty' in file_type:
                  print('-W- No criteria found: {} '.format(path))
              else:
                  print(
                      '-W- {} could not be read and may be improperly formatted...'.format(path))
      for rec in crit_data:
          # gather metadata
          metadata_dict = {'pmag_criteria_code': '',
                           'criteria_definition': '', 'er_citation_names': ''}
          for metadata in metadata_dict:
              if metadata in rec:
                  metadata_dict[metadata] = rec[metadata]
          # check each record for correct name and compatibility
          for crit in list(rec.keys()):
              if crit == 'anisotropy_ftest_flag' and crit not in list(rec.keys()):
                  crit = 'specimen_aniso_ftest_flag'  # convert legacy criterion to 2.5
              rec[crit] = rec[crit].strip('\n')
              if crit in ['pmag_criteria_code', 'criteria_definition', 'magic_experiment_names', 'er_citation_names']:
                  continue
              elif rec[crit] == "":
                  continue
  
              # this catches all the ones that are being overwritten
              if crit in acceptance_criteria:
                  if acceptance_criteria[crit]['value'] not in [-999, '-999', -999]:
  
                      print(
                          "-W- You have multiple different criteria that both use column: {}.\nThe last will be used:\n{}.".format(crit, rec))
                      warn_string = 'multiple criteria for column: {} (only last will be used)'.format(
                          crit)
                      if warn_string not in warnings:
                          warnings.append(warn_string)
              if crit == "specimen_dang" and "pmag_criteria_code" in list(rec.keys()) and "IE-SPEC" in rec["pmag_criteria_code"]:
                  crit = "specimen_int_dang"
                  print("-W- Found backward compatibility problem with selection criteria specimen_dang. Cannot be associated with IE-SPEC. Program assumes that the statistic is specimen_int_dang")
                  if 'specimen_int_dang' not in acceptance_criteria:
                      acceptance_criteria["specimen_int_dang"] = {}
                  acceptance_criteria["specimen_int_dang"]['value'] = float(
                      rec["specimen_dang"])
  
              elif crit not in acceptance_criteria_list:
                  print(
                      "-W- WARNING: criteria code %s is not supported by PmagPy GUI. please check" % crit)
                  acceptance_criteria[crit] = {}
                  acceptance_criteria[crit]['value'] = rec[crit]
                  acceptance_criteria[crit]['threshold_type'] = "inherited"
                  acceptance_criteria[crit]['decimal_points'] = -999
                  acceptance_criteria[crit]['category'] = None
              # boolean flag
              elif acceptance_criteria[crit]['threshold_type'] == 'bool':
                  if str(rec[crit]) in ['1', 'g', 'True', 'TRUE']:
                      acceptance_criteria[crit]['value'] = True
                  else:
                      acceptance_criteria[crit]['value'] = False
  
              # criteria as flags
              elif type(acceptance_criteria[crit]['threshold_type']) == list:
                  if str(rec[crit]) in acceptance_criteria[crit]['threshold_type']:
                      acceptance_criteria[crit]['value'] = str(rec[crit])
                  else:
                      print(
                          "-W- WARNING: data %s from criteria code  %s and is not supported by PmagPy GUI. please check" % (crit, rec[crit]))
              elif float(rec[crit]) == -999:
                  pass
              else:
                  acceptance_criteria[crit]['value'] = float(rec[crit])
              # add in metadata to each record
              acceptance_criteria[crit].update(metadata_dict)
      if "return_warnings" in kwargs:
          return (acceptance_criteria, warnings)
      else:
          return(acceptance_criteria)