docs: def thellier_magic(meas_file="measurements.txt", dir_path=".", input_dir_path="",
                     spec="", n_specs=5, save_plots=True,  fmt="svg", interactive=False,
                     contribution=None):
      """
      thellier_magic plots arai and other useful plots for Thellier-type experimental data
  
  
      Parameters
      ----------
      meas_file : str
          input measurement file, default "measurements.txt"
      dir_path : str
          output directory, default "."
          Note: if using Windows, all figures will be saved to working directly
                *not* dir_path
      input_dir_path : str
          input file directory IF different from dir_path, default ""
      spec : str
          default "", specimen to plot
      n_specs : int
          number of specimens to plot, default 5
          if you want to make all possible plots, specify "all"
      save_plots : bool, default True
          if True, create and save all requested plots
      fmt : str
          format of saved figures (default is 'svg')
      interactive : bool, default False
          interactively plot and display for each specimen
          (this is best used on the command line only)
      contribution : cb.Contribution, default None
          if provided, use Contribution object instead of reading in
          data from files
  
      Returns
      ---------
      status : True or False
      saved : list of figures saved
      """
  
      def make_plots(this_specimen, thel_data, cnt=1):
          """
          Take specimen name and measurement data
          and produce plots.
          Return a dictionary of plots created, or False if
          no plots could be created.
          """
          zed = False
          if pmagplotlib.verbose:
              print(this_specimen)
          # make the figure dictionary that pmagplotlib likes:
          #AZD = {'arai': 1, 'zijd': 2, 'eqarea': 3, 'deremag': 4}  # make datablock
          #if save_plots:
          #    AZD = {'arai': 1, 'zijd': 2, 'eqarea': 3, 'deremag': 4}  # make datablock
          #else:
          AZD = {'arai': cnt, 'zijd': cnt+1, 'eqarea': cnt +
                  2, 'deremag': cnt+3}  # make datablock
          #cnt += 4  # increment the figure counter
          spec_df = thel_data[thel_data.specimen ==
                              this_specimen]  # get data for this specimen
          # get the data block for Arai plot
          if len(spec_df) >= 3:
              # just skip specimen if arai data is malformed
              try:
                  araiblock, field = pmag.sortarai(spec_df, this_specimen, 0, version=3)
              except Exception as ex:
                  print('-W-', ex)
                  return zed
  
              if not save_plots:
                  for key, val in AZD.items():
                      pmagplotlib.plot_init(val, 5, 5)
  
          # get the datablock for Zijderveld plot
              zijdblock, units = pmag.find_dmag_rec(
                  this_specimen, spec_df, version=3)
              if not len(units):
                  unit_string = ""
              else:
                  unit_string = units[-1]
  
              zed = pmagplotlib.plot_arai_zij(
                  AZD, araiblock, zijdblock, this_specimen, unit_string)  # make the plots
          return zed
  
      # format some things
      if interactive:
          save_plots = False
  
      if not isinstance(contribution, cb.Contribution):
          # get proper paths
          input_dir_path, dir_path = pmag.fix_directories(input_dir_path, dir_path)
          file_path = pmag.resolve_file_name(meas_file, input_dir_path)
          input_dir_path = os.path.split(file_path)[0]
          # read in magic formatted data
          contribution = cb.Contribution(input_dir_path)
  
      if not contribution.tables.get('measurements'):
          print('-W- No measurements table found')
          return False, []
  
      try:
          contribution.propagate_location_to_samples()
          contribution.propagate_location_to_specimens()
          contribution.propagate_location_to_measurements()
      except KeyError as ex:
          pass
      meas_df = contribution.tables['measurements'].df
      # try to get contribution id for server plotting
      if pmagplotlib.isServer:
          con_id = contribution.get_con_id()
      # get key for intensity records
      int_key = cb.get_intensity_col(meas_df)
      # list for saved figs
      saved = []
      # get all the records with measurement data
      meas_data = meas_df[meas_df[int_key].notnull()]
      # get all the Thellier data
      thel_data = meas_data.dropna(subset=['method_codes'])
      thel_data = thel_data[thel_data['method_codes'].str.contains('LP-PI-TRM')]
      specimens = meas_data.specimen.unique()  # list of specimen names
      if len(specimens) == 0:
          print('there are no data for plotting')
          return False, []
      if spec:
          if spec not in specimens:
              print('could not find specimen {}'.format(spec))
              return False, []
          specimens = [spec]
      elif n_specs != "all":
          try:
              specimens = specimens[:n_specs]
          except Exception as ex:
              pass
      cnt = 1  # set the figure counter to 1
      for this_specimen in specimens:  # step through the specimens  list
          zed = make_plots(this_specimen, thel_data, cnt)
          # if plots were produced
          if zed:
              if interactive:
                  # draw and save interactively
                  pmagplotlib.draw_figs(zed)
                  ans = input(
                      "S[a]ve plots, [q]uit, <return> to continue\n ")
                  if ans == 'q':
                      return True, []
                  if ans == 'a':
                      files = {key : this_specimen + "_" + key + "." + fmt for (key, value) in zed.items()}
                      if not set_env.IS_WIN:
                          files = {key: os.path.join(dir_path, value) for (key, value) in files.items()}
                          incl_directory = True
                      saved.append(pmagplotlib.save_plots(zed, files, incl_directory=incl_directory))
  
              elif save_plots:
                  # don't draw, just save figures
                  files = {key : this_specimen + "_" + key + "." + fmt for (key, value) in zed.items()}
                  incl_directory = False
                  if not pmagplotlib.isServer:
                      # not server
                      if not set_env.IS_WIN:
                          files = {key: os.path.join(dir_path, value) for (key, value) in files.items()}
                          incl_directory = True
                  else:
                      # isServer, fix plot titles, formatting, and file names for server
                      for key, value in files.copy().items():
                          files[key] = "SP:_{}_TY:_{}_.{}".format(this_specimen, key, fmt)
                      titles = {}
                      titles['deremag'] = 'DeReMag Plot'
                      titles['zijd'] = 'Zijderveld Plot'
                      titles['arai'] = 'Arai Plot'
                      titles['TRM'] = 'TRM Acquisition data'
                      titles['eqarea'] = 'Equal Area Plot'
                      zed = pmagplotlib.add_borders(
                          zed, titles, con_id=con_id)
  
                  saved.append(pmagplotlib.save_plots(zed, files, incl_directory=incl_directory))
  
              # just let the plots appear (notebook)
              else:
                  cnt += len(zed)
                  # don't even need to draw 'em!  They just appear.
                  #pmagplotlib.draw_figs(zed)
          # no plots were produced
          else:
              print ('no data for ',this_specimen)
              print ('skipping')
      return True, saved