datasets¶
Dataset download and example-data utilities.
Functions to help download example datasets. The curated example datasets
(fetch_pain, fetch_emotion_ratings) are hosted on the nltools/niftis
Hugging Face dataset and resolve through the same fetch_resource machinery
as the MNI templates and atlases. Arbitrary Neurovault collections are still
available via fetch_neurovault_collection.
Methods:
| Name | Description |
|---|---|
download_nifti | Download an image from a URL to a nifti file. |
fetch_emotion_ratings | Download and load the emotion-rating dataset from the nltools HF dataset. |
fetch_neurovault_collection | Download images and metadata from a Neurovault collection. |
fetch_pain | Download and load the pain dataset from the nltools HF dataset. |
load_haxby_example | Load a small synthetic Haxby-like dataset, entirely in-memory. |
Classes¶
Methods¶
download_nifti¶
download_nifti(url, data_dir = None)Download an image from a URL to a nifti file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url | str | URL of the image to download | required |
data_dir | str | Directory to save the file. If None, uses current directory. | None |
Returns:
| Name | Type | Description |
|---|---|---|
str | Path to the downloaded file |
fetch_emotion_ratings¶
fetch_emotion_ratings(verbose = 0)Download and load the emotion-rating dataset from the nltools HF dataset.
Loads the Chang et al. (2015) IAPS emotion-rating study: 679 whole-brain
contrast images across 150 subjects, each rating images 1-5, with a
built-in train/test holdout split. X carries the full portable Neurovault
metadata (key columns: SubjectID, Rating, Holdout, AGE, SEX).
Data is hosted on the nltools/niftis Hugging Face dataset and cached
locally on first use, so this works with no extra setup.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verbose | int | Verbosity passed to BrainData while loading. Default: 0 | 0 |
Returns:
| Name | Type | Description |
|---|---|---|
BrainData | BrainData with the 679 images; X holds the metadata table. |
References
Chang, L. J., Gianaros, P. J., Manuck, S. B., Krishnan, A., & Wager, T. D. (2015). A sensitive and specific neural signature for picture-induced negative affect. PLoS biology, 13(6), e1002180.
fetch_neurovault_collection¶
fetch_neurovault_collection(collection_id, data_dir = None, verbose = 1)Download images and metadata from a Neurovault collection.
This function uses the modern nilearn API to download collections from Neurovault.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
collection_id | int | Neurovault collection ID | required |
data_dir | str | Directory to store downloaded data. If None, uses nilearn’s default data directory. | None |
verbose | int | Verbosity level. Default: 1 | 1 |
Returns:
| Name | Type | Description |
|---|---|---|
tuple | (metadata polars.DataFrame, list of image file paths) |
fetch_pain¶
fetch_pain(verbose = 0)Download and load the pain dataset from the nltools HF dataset.
Loads the Chang et al. (2015) pain-perception study: 28 subjects x 3
stimulus-intensity conditions = 84 whole-brain contrast images, with a
curated metadata table (SubjectID, PainLevel, PainIntensity, Age,
Sex, provenance neurovault_id / name).
Data is hosted on the nltools/niftis Hugging Face dataset and cached
locally on first use, so this works with no extra setup.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
verbose | int | Verbosity passed to BrainData while loading. Default: 0 | 0 |
Returns:
| Name | Type | Description |
|---|---|---|
BrainData | BrainData with the 84 images; X holds the metadata table. |
References
Chang, L. J., Gianaros, P. J., Manuck, S. B., Krishnan, A., & Wager, T. D. (2015). A sensitive and specific neural signature for picture-induced negative affect. PLoS biology, 13(6), e1002180.
load_haxby_example¶
load_haxby_example(n_runs = 1, random_state = 42)Load a small synthetic Haxby-like dataset, entirely in-memory.
Returns paired lists of BrainData and DesignMatrix, one entry per
run, generated from a tiny synthetic volume (10 x 10 x 5 = 500 voxels)
with condition-specific signal injected into disjoint voxel clusters.
No network I/O, no disk I/O, no nilearn fetcher dependency. Runs in
well under a second.
Intended for tutorials, documentation examples, and tests where downloading a real fMRI dataset is impractical. The eight conditions match the real Haxby 2001 object-recognition experiment (face, house, cat, bottle, scissors, shoe, chair, scrambledpix), arranged in a randomized 9-TR block design with TR=2.5s.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_runs | int | Number of runs to generate. Default 1. | 1 |
random_state | int | None | Seed for reproducible output. Default 42. | 42 |
Returns:
| Name | Type | Description |
|---|---|---|
tuple | (list[BrainData], list[DesignMatrix]), each of length n_runs. The DesignMatrix columns are the eight condition names suffixed with _c0 (HRF-convolved boxcars). |
Examples:
>>> from nltools.datasets import load_haxby_example
>>> brain_data, design_matrices = load_haxby_example()
>>> data, dm = brain_data[0], design_matrices[0]
>>> data.shape
(72, 500)
>>> "face_c0" in dm.columns
True