Datasets¶

The confusius.datasets module provides fetchers for publicly available atlases, templates, and fUSI datasets distributed in fUSI-BIDS format. Each fetcher downloads the dataset on first call, caches it locally for offline reuse, and returns either the path to the root directory, or a more specific object (e.g., a DataArray for templates or an atlas Dataset for atlases]).

Try before you buy

Fetchers generally accept filters (subjects, sessions, tasks, derivatives, etc.) so you can download a small subset first and decide later whether you want the full dataset. Cached files are never re-downloaded.

Quick Start¶

The fastest way to get started is to fetch a single subject from the Nunez-Elizalde 2022 dataset¹ and load one of its NIfTI files:

import confusius as cf
from confusius.datasets import fetch_nunez_elizalde_2022

# Download data for one mouse, one task, one brain slice (~30 MB).
root = fetch_nunez_elizalde_2022(
    subjects=["CR020"],
    sessions=["20191122"],
    tasks=["spontaneous"], 
    acqs=["slice03"],
)

# Load a power Doppler acquisition from the returned BIDS tree.
pwd = cf.load(
   root 
    / "sub-CR020"
    / "ses-20191122"
    / "fusi"
    / "sub-CR020_ses-20191122_task-spontaneous_acq-slice03_pwd.nii.gz"
)
print(pwd.dims)
# Output: ('time', 'z', 'y', 'x')

Datasets Storage¶

ConfUSIus resolves the cache directory using the following priority chain:

The data_dir argument passed to the fetcher.
The CONFUSIUS_DATA environment variable.
The platform cache directory (e.g. ~/.cache/confusius on Linux, ~/Library/Caches/confusius on macOS, %LOCALAPPDATA%\confusius\Cache on Windows).

You can inspect the resolved directory at any time with get_datasets_dir:

from confusius.datasets import get_datasets_dir

print(get_datasets_dir())
# /home/alice/.cache/confusius

Each fetcher creates its own BIDS-root subdirectory under this path (e.g. nunez-elizalde-2022-bids/), so multiple datasets can coexist safely.

Listing Available Datasets¶

Use list_datasets to print a table of available fetchers and their full download sizes:

from confusius.datasets import list_datasets

list_datasets()

                   Available Datasets
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓
┃ Fetch function                   ┃     Size ┃ On disk ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩
│ fetch_cybis_pereira_2026         │ 12.88 GB │    ✗    │
│ fetch_khallaf_2026               │ 19.49 GB │    ✗    │
│ fetch_landemard_2026             │ 42.04 GB │    ✗    │
│ fetch_nunez_elizalde_2022        │ 6.983 GB │    ✗    │
│ fetch_template_huang_2025        │ 16.34 MB │    ✗    │
│ fetch_template_pepe_mariani_2026 │ 5.508 MB │    ✗    │
└──────────────────────────────────┴──────────┴─────────┘

The sizes shown are for the full dataset. Filtered fetches are typically a small fraction of this (see the examples below).

The same table is available from the command line:

confusius datasets --list

Available fUSI-BIDS Datasets¶

Nunez-Elizalde 2022Cybis Pereira 2026Landemard 2026Khallaf 2026

Simultaneous neural activity and cerebral blood volume recordings in awake mice, from Nunez-Elizalde et al. (2022)¹, converted to fUSI-BIDS format and hosted on OSF (43skw). Total size: ~7 GB.

Use fetch_nunez_elizalde_2022 to download the dataset. Four filters narrow the download:

Filter	BIDS entity	Example
`subjects`	`sub-`	`["CR017", "CR020"]`
`sessions`	`ses-`	`["20191122"]`
`tasks`	`task-`	`["spontaneous"]`
`acqs`	`acq-`	`["slice03"]`

Angiography files are always included regardless of the tasks/acqs filters, since they are useful as anatomical references.

from confusius.datasets import fetch_nunez_elizalde_2022

# Two subjects, one task, one slice.
bids_root = fetch_nunez_elizalde_2022(
    subjects=["CR017", "CR020"],
    tasks=["spontaneous"],
    acqs=["slice03"],
)

Functional ultrasound imaging data from freely-moving rats investigating vascular coding of speed in the spatial navigation system, from Cybis Pereira et al. (2026)², hosted on OSF (2v6f7). Total size: ~13 GB.

Use fetch_cybis_pereira_2026 to download the dataset. Four filters narrow the download:

Filter	BIDS entity / scope	Example
`datasets`	dataset name	`"glm-speed"`, `["rawdata", "dlc-videos"]`
`subjects`	`sub-`	`["rat75", "rat73"]`
`sessions`	`ses-`	`["20220523"]`
`acqs`	`acq-`	`["slice32"]`

Files that lack a session or acquisition entity (e.g. subject-level statmaps in glm-speed, or decode-speed aggregates) are kept regardless of the sessions / acqs filters, since they aggregate across those entities.

The datasets filter accepts:

Name	Contents
`rawdata`	Raw fUSI acquisitions per subject
`glm-speed`	GLM outputs for linear speed
`glm-angular-speed`	GLM outputs for angular speed
`decode-speed`	Within-animal speed decoding results
`interanimal-decode-speed`	Inter-animal speed decoding results
`dlc-videos`	DeepLabCut behavior tracking videos

Derivatives are small relative to rawdata, so fetching a single derivative across all subjects is often the right first step:

from confusius.datasets import fetch_cybis_pereira_2026

# All subjects, GLM-speed derivative only.
bids_root = fetch_cybis_pereira_2026(datasets="glm-speed")

# Or raw data for a single subject, session, and acquisition slice.
bids_root = fetch_cybis_pereira_2026(
    datasets="rawdata",
    subjects="rat73",
    sessions="20220523",
    acqs="slice32",
)

Functional ultrasound imaging recordings from awake, head-fixed, freely-running mice, from Landemard et al. (2026)³, re-exported to fUSI-BIDS format and hosted on OSF (7cf9g). Total size: ~42 GB.

Use fetch_landemard_2026 to download the dataset. Four filters narrow the download:

Filter	BIDS entity / scope	Example
`datasets`	dataset name	`"atlas_mapping"`, `["rawdata", "processed_data"]`
`subjects`	`sub-`	`["ALD001", "ALD019"]`
`acqs`	`acq-`	`["ref04", "ref11"]`
`datatypes`	datatype directory	`"fusi"`, `["fusi", "angio"]`

The Landemard dataset has no session layer: every recording sits directly under sub-*/fusi/ or sub-*/angio/. Files that lack an acq- entity (e.g. sub-ALD001_scans.tsv, sub-ALD001/angio/sub-ALD001_pwd.nii.gz) are always included regardless of the acqs filter.

The datasets filter accepts:

Name	Contents
`rawdata`	Raw fUSI and angiography acquisitions per subject
`atlas_mapping`	Per-subject Allen atlas alignment and region/session matches
`processed_data`	Dataset-level compact representations, PSTHs, and ephys→fUSI filters

from confusius.datasets import fetch_landemard_2026

# All subjects, atlas_mapping derivative only.
bids_root = fetch_landemard_2026(datasets="atlas_mapping")

# Or raw fUSI data for a single subject, with a single acquisition.
bids_root = fetch_landemard_2026(
    datasets="rawdata",
    subjects="ALD001",
    acqs="ref04",
    datatypes="fusi",
)

Functional ultrasound imaging data from naked mole-rats exposed to olfactory stimulation, from Khallaf et al. (2026)⁴, organised following BIDS and the proposed fUSI extension BEP-040 and hosted on Edmond (10.17617/3.7QCU1F). Total size: ~19.5 GB.

Unlike the OSF-hosted datasets above, this one is distributed as a single ~19.5 GB zip archive. ConfUSIus streams the requested members out of it individually by HTTP range request, so a filtered fetch never downloads the whole archive.

Use fetch_khallaf_2026 to download the dataset. Six filters narrow the download:

Filter	BIDS entity / scope	Example
`datasets`	dataset name	`"glm"`, `["rawdata", "bootstrapping"]`
`subjects`	`sub-`	`"5622"`, `["5622", "6036"]`
`sessions`	`ses-`	`"IPM"`, `["Air", "Etoh"]`
`runs`	`run-`	`"1"`, `["1", "2"]`
`reconstruction`	`rec-`	`"raw"`, `"resampled"`, `"both"`
`sourcedata`	`sourcedata/` tree	`True`

Files that lack a subject, session, or run entity (e.g. participants.tsv, or group-level GLM maps) are kept regardless of those filters, since they aggregate across entities. subjects and runs also accept integers (subjects=5622).

The datasets filter accepts:

Name	Contents
`rawdata`	Raw fUSI acquisitions per subject
`glm`	GLM outputs, per-subject and group-level
`bootstrapping`	Bootstrapping derivative

The reconstruction filter applies only to rawdata fusi/ volumes: "raw" keeps the unregistered volumes (no rec- entity), "resampled" keeps the registered rec-resampled ones, and "both" (the default) keeps each.

The raw Iconeus acquisitions under sourcedata/ (~7.8 GB) are excluded by default. Set sourcedata=True to include the whole tree; it is never entity-filtered.

from confusius.datasets import fetch_khallaf_2026

# All subjects, GLM derivative only.
bids_root = fetch_khallaf_2026(datasets="glm")

# Or the resampled raw data for a single subject, session, and run.
bids_root = fetch_khallaf_2026(
    datasets="rawdata",
    subjects="5622",
    sessions="IPM",
    runs="1",
    reconstruction="resampled",
)

Working with fUSI-BIDS Datasets¶

fUSI-BIDS dataset fetchers return a pathlib.Path to the dataset's root directory. You may want to use the PyBIDS package for querying files, or simply use pathlib for quick exploration:

# List every power Doppler NIfTI for one subject.
for nii in sorted((bids_root / "sub-CR020").rglob("*_pwd.nii.gz")):
    print(nii.relative_to(bids_root))

See the I/O guide for loading NIfTI, Zarr, and Iconeus SCAN files into Xarray DataArrays.

Refreshing the Dataset Index¶

Each fUSI-BIDS dataset fetcher caches a dataset_index.json file mapping BIDS-relative paths to OSF file metadata (download path and size). Pass refresh=True to re-fetch this index from OSF and download any new files that appeared since the last call:

# Pick up any files added to OSF since the last fetch.
bids_root = fetch_nunez_elizalde_2022(subjects=["CR020"], refresh=True)

Existing local files are never re-downloaded—refresh=True only adds what is missing.

Available Templates¶

Huang 2025Pepe Mariani 2026

A vascular mouse fUSI template derived from Huang et al. (2025)⁵ and distributed as a single NIfTI on OSF (am3jw). Total size: ~16.3 MB.

Use fetch_template_huang_2025 to download and load the template directly:

from confusius.datasets import fetch_brainglobe_atlas, fetch_template_huang_2025

template = fetch_template_huang_2025()
atlas = fetch_brainglobe_atlas("allen_mouse_50um")
resampled_atlas = atlas.atlas.resample_like(
    template,
    template.attrs["affines"]["physical_to_sform"],
)

A mouse fUSI template derived from Pepe, Mariani et al. (2026)⁶ and distributed as a single NIfTI on OSF (43tu9). Total size: ~5.5 MB.

Use fetch_template_pepe_mariani_2026 to download and load the template directly:

from confusius.datasets import fetch_brainglobe_atlas, fetch_template_pepe_mariani_2026

template = fetch_template_pepe_mariani_2026()
atlas = fetch_brainglobe_atlas("allen_mouse_100um")
resampled_atlas = atlas.atlas.resample_like(
    template,
    template.attrs["affines"]["physical_to_sform"],
)

Available Brain Atlases¶

fetch_brainglobe_atlas fetches any BrainGlobe atlas by name and returns it as an atlas xarray.Dataset. ConfUSIus provides the .atlas accessor for common atlas operations like resampling, masking, and region lookups:

from confusius.datasets import fetch_brainglobe_atlas

atlas = fetch_brainglobe_atlas("allen_mouse_100um")
masks = atlas.atlas.get_masks("VISp")

Unlike the fUSI-BIDS datasets above, BrainGlobe atlases are cached in BrainGlobe's own atlas directory (~/.brainglobe, shared with other BrainGlobe tools), so they do not appear in list_datasets. Use data_dir to override the cache location.

API Reference¶

See the confusius.datasets API reference for the full list of parameters and return types.

Nunez-Elizalde, A.O. et al. (2022). Neural correlates of blood flow measured by ultrasound. Neuron, 110(10), 1631–1640. https://doi.org/10.1016/j.neuron.2022.02.012 ↩↩
Cybis Pereira, F. et al. (2026). A vascular code for speed in the spatial navigation system. Cell Reports, 45(1). https://doi.org/10.1016/j.celrep.2025.116791 ↩
Landemard, A., Krumin, M., Harris, K. D., & Carandini, M. (2026). Brainwide blood volume reflects opposing neural populations. Nature. https://doi.org/10.1038/s41586-026-10350-9 ↩
Khallaf, M. A. et al. (2026). A queen odour mediates reproductive suppression in a eusocial mammal. Nature. https://doi.org/10.1038/s41586-026-10772-5 ↩
Huang, Y.-A. et al. (2025). OfUSA: OpenfUS Analyzer, a versatile open-source framework for the analysis and visualization of functional ultrasound imaging data across animal models. https://doi.org/10.1101/2025.09.16.676515 ↩
Pepe, C. et al. (2026). Structural and dynamic embedding of the mouse functional connectome revealed by functional ultrasound imaging (fUSI). https://doi.org/10.64898/2026.02.05.704055 ↩