nispace.datasets.fetch_parcellation

nispace.datasets.fetch_parcellation(parcellation='Yan200', space=None, hemi=['L', 'R'], bilateral=False, return_parcellation_only=False, return_labels=True, return_space=False, return_resolution=False, return_symmetric=False, return_dist_mat=False, return_spin_mat=False, return_loaded=True, nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)[source]

Fetch a parcellation, as a Parcellation object (preferred) or, in legacy mode, as individual loaded arrays/paths.

Parameters:

  • parcellation (str or tuple of str, default from nispace.core.constants._PARC_DEFAULT) – Registered parcellation name (e.g. "Schaefer100"), a “+”-combined cortex+subcortex name (e.g. "Schaefer100+TianS1"), or a tuple of two such names.

  • space (str, optional) – Template space to fetch/activate (e.g. "MNI152NLin6Asym", "fsLR"). If None (default), no space is activated up front — a Parcellation is returned lazily configured to load spaces on demand, and return_parcellation_only is implied.

  • hemi (str or list of str, default ["L", "R"]) – Hemisphere(s) to restrict to (surface spaces only). A single hemisphere triggers Parcellation.select_hemi() on the returned object (new path).

  • bilateral (bool, default False) – If True, call Parcellation.make_bilateral() on the returned object (new path only; requires a symmetric parcellation).

  • return_parcellation_only (bool, default False) – If True (or if space is None), return a Parcellation object instead of individual arrays. This is the preferred, non-deprecated mode.

  • return_labels (bool) – Legacy mode only (ignored when a Parcellation object is returned): which additional pieces of information to include in the output tuple. return_labels defaults to True; the rest default to False.

  • return_space (bool) – Legacy mode only (ignored when a Parcellation object is returned): which additional pieces of information to include in the output tuple. return_labels defaults to True; the rest default to False.

  • return_resolution (bool) – Legacy mode only (ignored when a Parcellation object is returned): which additional pieces of information to include in the output tuple. return_labels defaults to True; the rest default to False.

  • return_symmetric (bool) – Legacy mode only (ignored when a Parcellation object is returned): which additional pieces of information to include in the output tuple. return_labels defaults to True; the rest default to False.

  • return_dist_mat (bool) – Legacy mode only (ignored when a Parcellation object is returned): which additional pieces of information to include in the output tuple. return_labels defaults to True; the rest default to False.

  • return_spin_mat (bool) – Legacy mode only (ignored when a Parcellation object is returned): which additional pieces of information to include in the output tuple. return_labels defaults to True; the rest default to False.

  • return_loaded (bool, default True) – Legacy mode only: whether to return loaded objects (nifti/gifti images, label lists, arrays) instead of file paths.

  • nispace_data_dir (str or Path, optional) – Deprecated; use the NISPACE_DATA_DIR environment variable instead.

  • overwrite (bool, default False) – Re-download files even if already cached locally.

  • check_file_hash (bool, default True) – Verify the SHA-256 hash of cached files against the known reference hash.

  • verbose (bool, default True) – Print progress messages.

Returns:

  • Parcellation – If space is None or return_parcellation_only=True (the preferred path).

  • object or tuple – Legacy path only (deprecated): a single value if only one return_* flag is set, otherwise a tuple in the order parc/label/space/res/sym/distmat/spinmat (only including the requested ones); for a cortex+subcortex parcellation, the two are merged (with distmat/spinmat returned as None, not yet supported for merged parcellations).

Notes

The legacy array-returning path (triggered when space is given explicitly and return_parcellation_only=False) is deprecated and will be removed in the first non-dev release. Prefer omitting space (or passing return_parcellation_only=True) and using the returned Parcellation object’s get_image()/get_dist_mat()/etc. methods instead.