docs: def subject(name, meta_data=None, check_path=True):
      '''
      subject(name) yields a freesurfer Subject object for the subject with the given name. Subjects
        are cached and not reloaded, so multiple calls to subject(name) will yield the same immutable
        subject object..
  
      Note that subects returned by freesurfer_subject() are always persistent Immutable objects; this
      means that you must create a transient version of the subject to modify it via the member
      function sub.transient(). Better, you can make copies of the objects with desired modifications
      using the copy method--see the pimms library documentation regarding immutable classes and
      objects.
  
      The following options are accepted:
        * meta_data (default: None) may optionally be a map that contains meta-data to be passed along
          to the subject object (note that this meta-data will not be cached).
        * check_path (default: True) may optionally be set to False to ignore the requirement that a
          directory contain at least the mri/, label/, and surf/ directories to be considered a valid
          FreeSurfer subject directory. Subject objects returned using this argument are not cached.
          Additionally, check_path may be set to None instead of False, indicating that no checks or
          search should be performed; the string name should be trusted to be an exact relative or
          absolute path to a valid FreeSurfer subejct.
      '''
      name = os.path.expanduser(os.path.expandvars(name))
      if check_path is None:
          sub = Subject(name, check_path=False)
          if isinstance(sub, Subject): sub.persist()
      else:
          subpath = find_subject_path(name, check_path=check_path)
          if subpath is None and name == 'fsaverage':
              # we can use the benson and winawer 2018 dataset
              import neuropythy as ny
              try: return ny.data['benson_winawer_2018'].subjects['fsaverage']
              except Exception: pass # error message below is more accurate...
          if subpath is None:
              raise ValueError('Could not locate subject with name \'%s\'' % name)
          elif check_path:
              fpath = '/' + os.path.relpath(subpath, '/')
              if fpath in subject._cache:
                  sub = subject._cache[fpath]
              else:
                  sub = Subject(subpath)
                  if isinstance(sub, Subject): subject._cache[fpath] = sub.persist()
          else:
              sub = Subject(subpath, check_path=False)
              if isinstance(sub, Subject): sub.persist()
      return (None                     if sub is None           else
              sub.with_meta(meta_data) if meta_data is not None else
              sub)