nltools.datasets¶

Example datasets, Neurovault collections, the files bundled with the package, and the atlas lookups.

Dataset, resource, and atlas lookups.

Functions to fetch example datasets, bundled resources, and parcellations. 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 available via fetch_neurovault_collection, and list_atlases / load_atlas / label_coords cover the parcellations.

Functions:

Name	Description
`fetch_pain`	Download and load the pain dataset from the nltools HF dataset.
`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.
`load_haxby_example`	Load a small synthetic Haxby-like dataset, entirely in-memory.
`download_nifti`	Download an image from a URL to a nifti file.
`get_resource_path`	Get the path to the nltools resource directory.
`fetch_resource`	Return a local path to a file from the `nltools/niftis` HF dataset.
`list_resources`	List files available in the `nltools/niftis` HF dataset.
`list_atlases`	Return the sorted list of registered atlas names.
`load_atlas`	Lazy-load an atlas by registry name.
`label_coords`	Look up anatomical labels for a set of MNI mm coordinates.

Functions:¶

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:

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.

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:

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; `0` is silent, including the data-directory line nilearn reports whatever it is asked for. Default: 1	`1`

Returns:

Type	Description
`tuple[DataFrame, list[str]]`	`(metadata, files)` — the image metadata table and the downloaded image paths.

Raises:

Type	Description
`ValueError`	If collection_id is invalid
`RuntimeError`	If download fails

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:

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

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:

Type	Description
`str`	Path to the downloaded file

Raises:

Type	Description
`ImportError`	If requests is not available
`ValueError`	If URL is invalid

get_resource_path ¶

get_resource_path()

Get the path to the nltools resource directory.

Returns:

Type	Description
`str`	Absolute path to `nltools/resources/`, with a trailing separator.

fetch_resource `cached` ¶

fetch_resource(relpath: str) -> str

Return a local path to a file from the nltools/niftis HF dataset.

Parameters:

Name	Type	Description	Default
`relpath`	`str`	Path within the dataset repo, e.g. `'default/2mm-MNI152-2009fsl-mask.nii.gz'` or `'masks/k88_parcel_names.csv'`. Use `list_resources` to enumerate what's available.	required

Returns:

Type	Description
`str`	Absolute path to the cached file on disk. The returned path drops straight into anything that takes a NIfTI path — nilearn plotting and masking helpers, `nibabel.load`, and `BrainData(path)`.

Note

Resolution is memoized per relpath for the session — repeated calls (e.g. every default-mask BrainData construction) return the cached path with no work. A file already in the HF cache is resolved offline, so only a genuine cache miss touches the network.

list_resources ¶

list_resources(prefix: str | None = None) -> list[str]

List files available in the nltools/niftis HF dataset.

Companion to fetch_resource — surfaces what's downloadable without forcing users to remember relpath strings or visit the HF web UI.

Parameters:

Name	Type	Description	Default
`prefix`	`str`	Path prefix to filter by (e.g. `'masks/'`, `'default/'`, `'fmriprep/'`). Matches with `str.startswith`.	`None`

Returns:

Type	Description
`list[str]`	Sorted relative paths usable with `fetch_resource`.

Note

Hits the HF API once per session (cached).

list_atlases ¶

list_atlases() -> list[str]

Return the sorted list of registered atlas names.

Returns:

Type	Description
`list[str]`	Sorted list of atlas names usable with `load_atlas`.

load_atlas `cached` ¶

load_atlas(name: str) -> Atlas

Lazy-load an atlas by registry name.

The first call fetches the NIfTI + label CSV from huggingface.co/datasets/nltools/niftis (cached locally afterwards). Subsequent calls in the same process are memoized.

Parameters:

Name	Type	Description	Default
`name`	`str`	Atlas key from `list_atlases`.	required

Returns:

Type	Description
`Atlas`	The atlas with image, labels, and metadata loaded.

Raises:

Type	Description
`ValueError`	If `name` isn't a registered atlas.

label_coords ¶

label_coords(
    coords: CoordsLike,
    *,
    atlas: str | Sequence[str] = "harvard_oxford",
    prob_threshold: float = 5.0,
) -> DataFrame

Look up anatomical labels for a set of MNI mm coordinates.

For each coordinate, returns the atlas region(s) it falls in. Works for both deterministic atlases (single label per coord) and probabilistic atlases (formatted "42.0% Foo; 18.0% Bar" strings, sorted by descending probability).

Parameters:

Name	Type	Description	Default
`coords`	`array - like`	`(N, 3)` MNI mm coordinates `(x, y, z)`. A single coordinate like `(-42, -22, 56)` is also accepted.	required
`atlas`	`str \| Sequence[str]`	Atlas name or list of names from `list_atlases`. One column is added to the output per atlas. Default `'harvard_oxford'`.	`'harvard_oxford'`
`prob_threshold`	`float`	For probabilistic atlases only — drop regions with probability (in percent units) below this threshold. Default 5.0.	`5.0`

Returns:

Type	Description
`DataFrame`	Frame with columns `x`, `y`, `z` plus one column per atlas. All atlas columns are `Utf8`.

nltools.datasets¶

Functions:¶

fetch_pain ¶

fetch_emotion_ratings ¶

fetch_neurovault_collection ¶

load_haxby_example ¶

download_nifti ¶

get_resource_path ¶

fetch_resource cached ¶

list_resources ¶

list_atlases ¶

load_atlas cached ¶

label_coords ¶

fetch_resource `cached` ¶

load_atlas `cached` ¶