docs: def calc_atlases(worklog, atlas_subject_id='fsaverage'):
      '''
      cacl_atlases finds all available atlases in the possible subject directories of the given atlas
      subject.
  
      In order to be a template, it must either be a collection of files (either mgh/mgz or FreeSurfer
      curv/morph-data files) named as '<hemi>.<template>_<quantity><ending>' such as the files
      'lh.wang2015_mplbl.mgz' and 'rh.wang2015_mplbl.mgz'. They may additionally have a version
      prior to the ending, as in 'lh.benson14_angle.v2_5.mgz'. Files without versions are considered 
      to be of a higher version than all versioned files. All files must be found in the atlas
      subject's surf/ directory; however, all subjects in all FreeSurfer subjects paths with the same
      subject id are searched if the atlas is not found in the atlas subejct's directory.
  
      Afferent parameters:
        @ atlas_subject_id 
          The FreeSurfer subject name subject path of the subject that is to be used as the atlas
          subject from which the atlas is interpolated. HCP subjects are not currently supported.
  
      Efferent values:
        @ atlas_map 
          A persistent map whose keys are atlas names, the values of which are themselves persistent
          maps whose keys are the versions of the given atlas (None potentially being included). The
          values of these maps are again maps of hemisphere names then finally of the of the quantity
          names (such as 'eccen' or 'maxprob') to the property vectors imported from the appropriate
          files.
      '''
      try:              sub = freesurfer_subject(atlas_subject_id)
      except Exception: sub = None
      if sub is None:
          try: sub = hcp_subject(atlas_subject_id)
          except Exception: sub = None
      if sub is None: raise ValueError('Could not load atlas subject %s' % atlas_subject_id)
      worklog('Using Atlas subject: %s' % sub.path)
      # Now find the requested atlases
      atlases = AutoDict()
      atlas_patt = r'^([lr]h)\.([^_]+)_([^.]+)(\.(v(\d+(_\d+)*)))?((\.mg[hz])|\.nii(\.gz)?)?$'
      atlas_hemi_ii = 1
      atlas_atls_ii = 2
      atlas_meas_ii = 3
      atlas_vrsn_ii = 6
      libdir = os.path.join(library_path(), 'data')
      for pth in [libdir] + config['freesurfer_subject_paths'] + [sub.path]:
          # see if appropriate files are in this directory
          pth = os.path.join(pth, sub.name, 'surf')
          if not os.path.isdir(pth): continue
          for fl in os.listdir(pth):
              m = re.match(atlas_patt, fl)
              if m is None: continue
              fl = os.path.join(pth, fl)
              (h, atls, meas, vrsn) = [
                  m.group(ii) for ii in (atlas_hemi_ii, atlas_atls_ii, atlas_meas_ii, atlas_vrsn_ii)]
              if vrsn is not None: vrsn = tuple([int(s) for s in vrsn.split('_')])
              atlases[atls][vrsn][h][meas] = curry(nyio.load, fl)
      # convert the possible atlas maps into persistent/lazy maps
      atlas_map = pyr.pmap({a:pyr.pmap({v:pyr.pmap({h:pimms.lazy_map(hv)
                                                    for (h,hv) in six.iteritems(vv)})
                                        for (v,vv) in six.iteritems(av)})
                            for (a,av) in six.iteritems(atlases)})
      return {'atlas_map':atlas_map, 'atlas_subject':sub}