@nyio.importer('<STR_LIT>', sniff=is_freesurfer_subject_path)<EOL>def subject(name, meta_data=None, check_path=True):
name = os.path.expanduser(os.path.expandvars(name))<EOL>if check_path is None:<EOL><INDENT>sub = Subject(name, check_path=False)<EOL>if isinstance(sub, Subject): sub.persist()<EOL><DEDENT>else:<EOL><INDENT>subpath = find_subject_path(name, check_path=check_path)<EOL>if subpath is None and name == '<STR_LIT>':<EOL><INDENT>import neuropythy as ny<EOL>try: return ny.data['<STR_LIT>'].subjects['<STR_LIT>']<EOL>except Exception: pass <EOL><DEDENT>if subpath is None:<EOL><INDENT>raise ValueError('<STR_LIT>' % name)<EOL><DEDENT>elif check_path:<EOL><INDENT>fpath = '<STR_LIT:/>' + os.path.relpath(subpath, '<STR_LIT:/>')<EOL>if fpath in subject._cache:<EOL><INDENT>sub = subject._cache[fpath]<EOL><DEDENT>else:<EOL><INDENT>sub = Subject(subpath)<EOL>if isinstance(sub, Subject): subject._cache[fpath] = sub.persist()<EOL><DEDENT><DEDENT>else:<EOL><INDENT>sub = Subject(subpath, check_path=False)<EOL>if isinstance(sub, Subject): sub.persist()<EOL><DEDENT><DEDENT>return (None                     if sub is None           else<EOL>sub.with_meta(meta_data) if meta_data is not None else<EOL>sub)<EOL>
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.