docs: def calc_filemap(atlas_properties, subject, atlas_version_tags, worklog,
                   output_path=None, overwrite=False, output_format='mgz', create_directory=False):
      '''
      calc_filemap is a calculator that converts the atlas properties nested-map into a single-depth
      map whose keys are filenames and whose values are the interpolated property data.
  
      Afferent parameters
        @ output_path 
          The directory into which the atlas files should be written. If not provided or None then
          uses the subject's surf directory. If this directory doesn't exist, then it uses the
          subject's directory itself.
        @ overwrite 
          Whether to overwrite existing atlas files. If True, then atlas files that already exist will
          be overwritten. If False, then no files are overwritten.
        @ create_directory 
          Whether to create the output path if it doesn't exist. This is False by default.
        @ output_format 
          The desired output format of the files to be written. May be one of the following: 'mgz',
          'mgh', or either 'curv' or 'morph'.
  
      Efferent values:
        @ filemap 
          A pimms lazy map whose keys are filenames and whose values are interpolated atlas
          properties.
        @ export_all_fn 
          A function of no arguments that, when called, exports all of the files in the filemap to the
          output_path.
      '''
      if output_path is None:
          output_path = os.path.join(subject.path, 'surf')
          if not os.path.isdir(output_path): output_path = subject.path
      output_format = 'mgz' if output_format is None else output_format.lower()
      if output_format.startswith('.'): output_format = output_format[1:]
      (fmt,ending) = (('mgh','.mgz') if output_format == 'mgz' else
                      ('mgh','.mgh') if output_format == 'mgh' else
                      ('freesurfer_morph',''))
      # make the filemap...
      worklog('Preparing Filemap...')
      fm = AutoDict()
      for (atl,atldat) in six.iteritems(atlas_properties):
          for (ver,verdat) in six.iteritems(atldat):
              vstr = atlas_version_tags[atl][ver]
              for (h,hdat) in six.iteritems(verdat):
                  for m in six.iterkeys(hdat):
                      flnm = '%s.%s_%s%s%s' % (h, atl, m, vstr, ending)
                      flnm = os.path.join(output_path, flnm)
                      fm[flnm] = curry(lambda hdat,m: hdat[m], hdat, m)
      # okay, make that a lazy map:
      filemap = pimms.lazy_map(fm)
      # the function for exporting all properties:
      def export_all():
          '''
          This function will export all files from its associated filemap and return a list of the
          filenames.
          '''
          if not os.path.isdir(output_path):
              if not create_directory:
                  raise ValueError('No such path and create_direcotry is False: %s' % output_path)
              os.makedirs(os.path.abspath(output_path), 0o755)
          filenames = []
          worklog('Extracting Files...')
          wl = worklog.indent()
          for flnm in six.iterkeys(filemap):
              wl(flnm)
              filenames.append(nyio.save(flnm, filemap[flnm], fmt))
          return filenames
      return {'filemap': filemap, 'export_all_fn': export_all}