nispace.datasets.fetch_reference

nispace.datasets.fetch_reference(dataset, maps=None, space=None, collection=None, sets=None, set_size_range=None, weight_range=None, weight_quantile=None, set_top_n=None, set_specificity=None, parcellation=None, bilateral=False, hemi=None, standardize_parcellated=False, return_metadata=False, print_references=True, osf_config_file=None, github_config_file=None, nispace_data_dir=None, overwrite=False, check_file_hash=True, verbose=True)[source]

Fetch reference/annotation maps (or parcellated data derived from them) for a dataset.

This is the main entry point for NiSpace’s integrated reference datasets (e.g. PET tracer maps, mRNA expression, ENIGMA disorder maps). Depending on whether parcellation is given, it returns either paths to the raw map images or already-parcellated tabular data; maps/collection/sets narrow down which maps are returned.

Parameters:

  • dataset (str) – Name of an integrated reference dataset (e.g. "pet", "mrna", "enigma"). See fetch_collection/the online docs for the full list.

  • maps (str, list of str, or dict, optional) – Restrict to a subset of map IDs. A string/list is matched as a substring against available map names; a dict is matched as {filter_name: value(s)} filters (e.g. {"n": ">20"} on sample size). None keeps all maps.

  • space (str, optional) – Template space for the raw map images (only used when parcellation is None). Auto-selected (preferring the package’s default volumetric, then surface, space) if not given.

  • collection (str, optional) – Name of an integrated collection to filter/group maps by (see fetch_collection()); "All" is equivalent to not filtering.

  • sets (str or list of str, optional) – Restrict to specific named sets within collection. Requires collection to define sets.

  • set_size_range (tuple (int, int), optional) – Keep only collection sets whose membership count falls within this range. Forwarded to fetch_collection().

  • weight_range (tuple (float, float), optional) – Keep only weighted collection entries within this weight range. Forwarded to fetch_collection().

  • weight_quantile (float, optional) – Within each collection set, keep only entries at or above this weight quantile. Forwarded to fetch_collection().

  • set_top_n (int, optional) – Within each collection set, keep only the top-n entries by weight. Forwarded to fetch_collection().

  • set_specificity (float, optional) – Keep only maps appearing in at most this fraction of collection sets. Forwarded to fetch_collection().

  • parcellation (str, tuple of str, or Parcellation, optional) – If given, return parcellated tabular data instead of image paths. Accepts a registered parcellation name, a cortex+subcortex tuple, a “+”-combined name, or a Parcellation object (its name is extracted automatically).

  • bilateral (bool, default False) – If True (and parcellation is symmetric), average matched left/right columns into single bilateral parcels. Only meaningful with parcellation.

  • hemi (str or list of str, optional) – Restrict to one hemisphere ("L" or "R"). For parcellated data, keeps only columns with the matching hemi-* label prefix; has no effect on raw image paths.

  • standardize_parcellated (bool, default False) – If True, z-score parcellated data across maps (forwarded to zscore_df()). Only used with parcellation.

  • return_metadata (bool, default False) – If True, also return the dataset’s per-map metadata table (see fetch_map_info()) alongside the data.

  • print_references (bool, default True) – Print the dataset’s description and citation information (and, if return_metadata or metadata is otherwise loaded, a per-map citation table) to stdout.

  • osf_config_file (str, optional) – Path to an OSF credentials config file, required to access private maps hosted on OSF (see download_file()).

  • github_config_file (str, optional) – Path to a GitHub credentials config file, required to access private maps hosted on the private NiSpace-data GitHub repo.

  • 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:

If parcellation is None: a list of paths to the raw map images (or, for surface spaces, a list of (lh_path, rh_path) tuples), one per matched map. If parcellation is given: a DataFrame of shape (n_maps, n_parcels), indexed by map name (or a ["set", "map"]/["set", "map", "weight"] MultiIndex if collection groups maps into sets). If return_metadata=True: the above, plus the metadata DataFrame from fetch_map_info(), as a 2-tuple (or an n+1-tuple if the data itself was already a tuple of per-hemisphere paths).

Return type:

list, pd.DataFrame, or tuple

Raises:

  • ValueError – If dataset is not a registered dataset, requires a parcellation but none is given, or space/collection/sets/bilateral don’t match what’s available for the dataset.

  • TypeError – If dataset is not a string.