Loading data & masks

BrainData is the entry point. Hand its constructor a NIfTI path, a list of paths, a URL, an .h5 bundle, a nibabel image, another BrainData, or a numpy array plus a mask=. A list of paths stacks into one (n_images, n_voxels) object. The optional X and Y arguments attach per-image tables (design/covariates and targets) that travel with the data.

The mask decides the grid. With no mask=, nltools uses the bundled MNI template at the brain space's current resolution. If your data sits on a grid no bundled template matches, say 4 mm, nltools resamples it to the closest bundled ½/3 mm template and raises a ResamplingWarning naming the fallback. To keep the native resolution, pass mask= with a mask in your data's own space. Template names follow the '{res}mm-MNI152-2009{version}' pattern, where the version code is fsl (default, ⅔ mm), a (nilearn, ½/3 mm), or c (fmriprep, ½ mm).

Goal	Use	Notes
Load one or many images	`BrainData(path_or_list)`	List input stacks; mixed grids are resampled to the mask
Use a specific grid	`BrainData(..., mask='3mm-MNI152-2009fsl')`	Also accepts a `Nifti1Image` or a mask path
Change the global default	`set_brainspace` / `with_brainspace`	`with_brainspace` is a context manager; `reset_brainspace` restores defaults
Save / reload with metadata	`BrainData.write` → `.h5`	HDF5 round-trips `X`, `Y`, and the mask; `.nii.gz` does not
Example data	`fetch_pain`, `fetch_emotion_ratings`, `load_haxby_example`	Cached on first use; `load_haxby_example` is synthetic and needs no network
Bundled masks and atlases	`list_resources`, `fetch_resource`	Returns a local path; parcellations live under `masks/`
Published maps	`fetch_neurovault_collection`, `download_nifti`	`BrainData` also accepts a URL directly
Build a mask	`create_sphere`, `expand_mask`, `collapse_mask`	`expand_mask` turns one labeled atlas into per-ROI binary masks
Stack objects	`concatenate`	Works on lists of `BrainData` or `Adjacency`

Loading¶

from nltools.data import BrainData
from nltools.datasets import fetch_pain

pain = fetch_pain()          # 84 images; the metadata table is in .X
stack = BrainData(paths, mask="3mm-MNI152-2009fsl")

Brain space and HDF5¶

set_brainspace changes the template every mask-less object falls back on for the rest of the session. Prefer with_brainspace when you only need the change for a few lines.

from nltools.templates import get_brainspace, set_brainspace, with_brainspace

set_brainspace(resolution=3)             # 3 mm from here on
with with_brainspace(resolution=2):      # 2 mm inside the block only
    coarse = BrainData(paths[0])

pain[:5].write("subset.h5")
subset = BrainData("subset.h5")          # X, Y, and mask come back intact

Bundled files¶

list_resources(prefix=...) browses the nltools/niftis dataset without downloading; fetch_resource downloads one file and returns its local path.

from nltools.templates import fetch_resource, list_resources
from nltools.mask import create_sphere

list_resources(prefix="default")
fetch_resource("default/2mm-MNI152-2009fsl-mask.nii.gz")
sphere = create_sphere([0, 20, 30], radius=8)

Next: Design matrices & GLM, or the BrainData tutorial for a worked walkthrough.