neuromaps_mouse.datasets.fetch_annotation

neuromaps_mouse.datasets.fetch_annotation(annotations, data_dir=None, return_single=False, verbose=1)[source]

Download and cache annotation files.

Fetches annotation data files from the neuromaps-mouse repository and caches them locally. Also downloads related metadata files such as region mappings.

Parameters:

  • annotations (str, tuple, or list of str/tuple) – Annotation(s) to fetch. Can be specified as: - A single annotation tuple from available_annotations() - A list of annotation tuples - A string identifier for a specific annotation - A list of string identifiers

  • data_dir (str or Path, optional) – Path to the base neuromaps-mouse data directory where files will be cached. If None, uses the default directory. Default is None.

  • return_single (bool, optional) – If True and only one annotation is requested, returns a tuple of (annotation_id, file_path). If False, always returns lists. Default is False.

  • verbose (int, optional) – Verbosity level for download progress (0=silent, 1=verbose). Default is 1.

Returns:

  • annotations (list of str or str) – Input annotation identifier(s). Returned as single string if return_single=True and one annotation was requested.

  • file_paths (list of str or str) – Path(s) to the downloaded annotation file(s). Returned as single string if return_single=True and one annotation was requested.

Notes

This function automatically downloads related metadata files (such as regionmapping files) for each annotation source. Files are cached locally to avoid re-downloading on subsequent calls.

See also

neuromaps_mouse.datasets.available_annotations

List available annotations.

neuromaps_mouse.datasets.get_annotation_dir

Get the annotations directory path.

Examples

>>> # Fetch a single annotation
>>> annot_id, annot_path = fetch_annotation(
...     ('lein2006amba', 'sagittalenergy', 'allenccfv3', 'region'),
...     return_single=True
... )
>>> print(f"Downloaded to: {annot_path}")

>>> # Fetch multiple annotations
>>> annot_ids, annot_paths = fetch_annotation([
...     ('lein2006amba', 'sagittalenergy', 'allenccfv3', 'region'),
...     ('yao2023abca', 'divimean', 'allenccfv3', 'region')
... ])