docs: def cache_mappings(file_path):
      """
      Make a full mapping for 2 --> 3 columns.
      Output the mapping to json in the specified file_path.
      Note: This file is currently called maps.py,
      full path is PmagPy/pmagpy/mapping/maps.py.
  
      Parameters
      ----------
      file_path : string with full file path to dump mapping json.
  
      Returns
      ---------
      maps : nested dictionary with format {table_name: {magic2_col_name: magic3_col_name, ...}, ...}
      """
      def get_2_to_3(dm_type, dm):
          table_names3_2_table_names2 = {'measurements': ['magic_measurements'],
                                         'locations': ['er_locations'],
                                         'sites': ['er_sites', 'pmag_sites'],
                                         'samples': ['er_samples', 'pmag_samples'],
                                         'specimens': ['er_specimens', 'pmag_specimens'],
                                         'ages': ['er_ages'],
                                         'criteria': ['pmag_criteria'],
                                         'images': ['er_images'],
                                         'contribution': []}
          table_names3 = table_names3_2_table_names2[dm_type]
          dictionary = {}
          for label, row in dm.iterrows():
              # if there are one or more corresponding 2.5 columns:
              if isinstance(row['previous_columns'], list):
                  for previous_values in row['previous_columns']:
                      previous_table = previous_values['table']
                      previous_value = previous_values['column']
                      if previous_table in table_names3:
                          add_to_dict(previous_value, label, dictionary)
                      elif previous_table in ["pmag_results", "rmag_results"]:
                          if label not in dictionary.values():
                              if previous_value not in dictionary.keys():
                                  add_to_dict(previous_value, label, dictionary)
          return dictionary
  
      def add_to_dict(key, value, dictionary):
          if key in dictionary:
              if value != dictionary[key]:
                  print('W- OVERWRITING')
                  print('was:', key, dictionary[key])
                  print('now:', key, value)
          dictionary[key] = value
  
      # begin
      data_model = DataModel()
      maps = {}
      for table_name in data_model.dm:
          dm = data_model.dm[table_name]
          new_mapping = get_2_to_3(table_name, dm)
          maps[table_name] = new_mapping
      # write maps out to file
      f = open(file_path, 'w')
      f.write("all_maps = ")
      json.dump(maps, f)
      f.close()
      return maps