`confusius.datasets`¶

datasets ¶

Datasets for confusius examples and tutorials.

Functions:

fetch_cybis_pereira_2026 –

Fetch the Cybis Pereira 2026 fUSI-BIDS dataset.
fetch_nunez_elizalde_2022 –

Fetch the Nunez-Elizalde 2022 fUSI-BIDS dataset.
fetch_template_pepe_mariani_2026 –

Fetch the Pepe, Mariani et al. (2026) mouse fUSI template.
get_datasets_dir –

Return the confusius data directory.
list_datasets –

Print a table of available datasets.

fetch_cybis_pereira_2026 ¶

fetch_cybis_pereira_2026(
    data_dir: str | Path | None = None,
    datasets: str | list[str] | None = None,
    subjects: str | list[str] | None = None,
    sessions: str | list[str] | None = None,
    acqs: str | list[str] | None = None,
    refresh: bool = False,
) -> Path

Fetch the Cybis Pereira 2026 fUSI-BIDS dataset.

Downloads functional ultrasound imaging data from freely-moving rats investigating vascular coding of speed in the spatial navigation system, converted to fUSI-BIDS format from Cybis Pereira et al. (2026).

Files are downloaded on first call and cached locally. Subsequent calls with the same data_dir return immediately for already-cached files.

Parameters:

data_dir ¶
(str or Path, default: None ) –

Directory in which to cache the dataset. Defaults to the platform cache directory (e.g. ~/.cache/confusius on Linux, ~/Library/Caches/confusius on macOS, %LOCALAPPDATA%\confusius\Cache on Windows), overridable via the CONFUSIUS_DATA environment variable.
datasets ¶
(str or list[str], default: None ) –

Datasets to download. Use "rawdata" for the raw fUSI data and derivative names for processed outputs: "glm-speed", "glm-angular-speed", "decode-speed", "interanimal-decode-speed", "dlc-videos". Accepts a single string or a list. If not provided, all datasets are downloaded.
subjects ¶
(str or list[str], default: None ) –

Subject IDs to download (without "sub-" prefix), e.g. "rat73" or ["rat75", "rat73"]. If not provided, all subjects are downloaded.
sessions ¶
(str or list[str], default: None ) –

Session IDs to download (without "ses-" prefix), e.g. "20220523" or ["20220523", "20220524"]. If not provided, all sessions are downloaded. Files with no session entity (e.g. subject-level derivatives) are always included.
acqs ¶
(str or list[str], default: None ) –

Acquisition labels to download (without "acq-" prefix), e.g. "slice32" or ["slice32", "slice42"]. If not provided, all acquisitions are downloaded. Files with no acquisition entity are always included.
refresh ¶
(bool, default: False ) –

Whether to re-fetch the dataset index from OSF and download any files that are missing locally. If False and all requested files are already cached, the function returns immediately without any network access.

Returns:

Path –

Path to the BIDS root directory of the cached dataset.

Raises:

ValueError –

If an unknown dataset name is passed in datasets.

References

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 ↩
fUSI-BIDS dataset on OSF: https://osf.io/2v6f7/ ↩

fetch_nunez_elizalde_2022 ¶

fetch_nunez_elizalde_2022(
    data_dir: str | Path | None = None,
    subjects: str | list[str] | None = None,
    sessions: str | list[str] | None = None,
    tasks: str | list[str] | None = None,
    acqs: str | list[str] | None = None,
    refresh: bool = False,
) -> Path

Fetch the Nunez-Elizalde 2022 fUSI-BIDS dataset.

Downloads simultaneous neural activity and cerebral blood volume recordings in awake mice, converted to fUSI-BIDS format from Nunez-Elizalde et al. (2022).

Files are downloaded on first call and cached locally. Subsequent calls with the same data_dir return immediately for already-cached files.

Parameters:

data_dir ¶
(str or Path, default: None ) –

Directory in which to cache the dataset. Defaults to the platform cache directory (e.g. ~/.cache/confusius on Linux, ~/Library/Caches/confusius on macOS, %LOCALAPPDATA%\confusius\Cache on Windows), overridable via the CONFUSIUS_DATA environment variable.
subjects ¶
(str or list[str], default: None ) –

Subject IDs to download (without "sub-" prefix), e.g. "CR020" or ["CR020"]. Accepts a single string or a list. If not provided, all subjects are downloaded.
sessions ¶
(str or list[str], default: None ) –

Session IDs to download (without "ses-" prefix), e.g. "20191122" or ["20191122"]. Accepts a single string or a list. If not provided, all sessions are downloaded.
tasks ¶
(str or list[str], default: None ) –

Task names to download, e.g. "kalatsky" or ["kalatsky", "spontaneous"]. Accepts a single string or a list. If not provided, all tasks are downloaded. Angiography files are always included regardless of this filter.
acqs ¶
(str or list[str], default: None ) –

Acquisition labels to download (without acq-), e.g. "slice03" or ["slice03"]. Accepts a single string or a list. If not provided, all acquisitions are downloaded. Only applies to fusi/ files; angiography files are always included.
refresh ¶
(bool, default: False ) –

Whether to re-fetch the dataset index from OSF and download any files that are missing locally. If False and all requested files are already cached, the function returns immediately without any network access.

Returns:

Path –

Path to the BIDS root directory of the cached dataset.

References

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 ↩
fUSI-BIDS dataset on OSF: https://osf.io/43skw/ ↩

fetch_template_pepe_mariani_2026 ¶

fetch_template_pepe_mariani_2026(
    data_dir: str | Path | None = None,
    refresh: bool = False,
) -> DataArray

Fetch the Pepe, Mariani et al. (2026) mouse fUSI template.

Downloads the template from OSF on first call, caches it locally, and returns the loaded NIfTI as an Xarray DataArray.

Parameters:

data_dir ¶
(str or Path, default: None ) –

Directory in which to cache the template. Defaults to the platform cache directory (e.g. ~/.cache/confusius on Linux, ~/Library/Caches/confusius on macOS, %LOCALAPPDATA%\confusius\Cache on Windows), overridable via the CONFUSIUS_DATA environment variable.
refresh ¶
(bool, default: False ) –

Whether to redownload the template even if it is already cached.

Returns:

DataArray –

Template with physical_to_sform affine transform required for resampling to the Allen Mouse Brain atlas space.

References

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 ↩
Template hosted on OSF: https://osf.io/43tu9/ ↩

get_datasets_dir ¶

get_datasets_dir(
    data_dir: str | Path | None = None,
) -> Path

Return the confusius data directory.

Priority order:

The data_dir argument.
The CONFUSIUS_DATA environment variable.
The platform cache directory (e.g. ~/.cache/confusius on Linux).

Parameters:

data_dir ¶
(str or Path, default: None ) –

Custom data directory. If not provided, falls back to the environment variable or the platform cache.

Returns:

Path –

Resolved data directory (created if it does not exist).

list_datasets ¶

list_datasets(data_dir: str | Path | None = None) -> None

Print a table of available datasets.

Parameters:

data_dir ¶
(str or Path, default: None ) –

Cache directory to check for existing datasets. Defaults to the directory resolved by get_datasets_dir.

`confusius.datasets`¶

datasets ¶

fetch_cybis_pereira_2026 ¶

`data_dir` ¶

`datasets` ¶

`subjects` ¶

`sessions` ¶

`acqs` ¶

`refresh` ¶

fetch_nunez_elizalde_2022 ¶

`data_dir` ¶

`subjects` ¶

`sessions` ¶

`tasks` ¶

`acqs` ¶

`refresh` ¶

fetch_template_pepe_mariani_2026 ¶

`data_dir` ¶

`refresh` ¶

get_datasets_dir ¶

`data_dir` ¶

list_datasets ¶

`data_dir` ¶

confusius.datasets¶

datasets ¶

fetch_cybis_pereira_2026 ¶

data_dir ¶

datasets ¶

subjects ¶

sessions ¶

acqs ¶

refresh ¶

fetch_nunez_elizalde_2022 ¶

data_dir ¶

subjects ¶

sessions ¶

tasks ¶

acqs ¶

refresh ¶

fetch_template_pepe_mariani_2026 ¶

data_dir ¶

refresh ¶

get_datasets_dir ¶

data_dir ¶

list_datasets ¶

data_dir ¶

`confusius.datasets`¶

`data_dir` ¶

`datasets` ¶

`subjects` ¶

`sessions` ¶

`acqs` ¶

`refresh` ¶

`data_dir` ¶

`subjects` ¶

`sessions` ¶

`tasks` ¶

`acqs` ¶

`refresh` ¶

`data_dir` ¶

`refresh` ¶

`data_dir` ¶

`data_dir` ¶