In 30 seconds

Python neuroimaging API

Spatially safe neuroimaging, without ceremony.

Typed volumes, voxel-series containers, and provenance receipts that keep analyses honest across in-memory, file-backed, and derived-data workflows.

Start here → API reference Read the spec

Spatial contracts Recoverable provenance One protocol

quickstart.py

import neuroim as ni

bold = ni.read_image("bold.nii.gz")
mask = ni.read_image("mask.nii.gz", type="vol")

# Refuses mismatched spatial frames early
bold.space.compatible_with(mask.space)

roi = ni.spherical_roi(mask, centroid=(42, 54, 38), radius=6)
result = bold.series_roi(roi)

result.values.shape
result.provenance.method_name

Coming from nibabel or nilearn? See the evidence →

22 worked scenarios, each a real task run both ways and checked at build time — see the evidence →.

A masked temporal-SNR map, start to finish. You read a BOLD and a mask, compute the map, and the result already knows the image and mask it came from — and still knows after a save/reload through a .nii.gz. The frame check that would otherwise be a line you have to remember is just part of the call.

from pathlib import Path
import sys

sys.path.insert(0, str(Path.cwd().parent / "src"))

import neuroim as ni

repo = Path.cwd().parent if Path.cwd().name == "docs" else Path.cwd()
bold = ni.read_image(str(repo / "golden_tests/fixtures/tiny_bold.nii.gz"))
mask = ni.read_image(str(repo / "golden_tests/fixtures/tiny_mask.nii.gz"), type="vol")

tsnr = bold.temporal_snr(mask=mask)
(tsnr.shape,
 tsnr.provenance.method_name,
 tsnr.provenance.input_space_hash[:12],
 tsnr.provenance.mask_hash[:12])
((np.int64(8), np.int64(8), np.int64(4)),
 'temporal_snr',
 'd0f6bff35b9c',
 '649ca2f312df')

After nib.save(tsnr.to_nibabel(), "tsnr.nii.gz"), a fresh process calling ni.read_image("tsnr.nii.gz") returns a DenseNeuroVol with .provenance rehydrated from the NIfTI extension. No sidecar JSON. No hand-curated manifest. The round-trip page shows the full pattern.

Three promises

Contracts at the surface

Public operations check spatial inputs before returning a value, so shape, affine, and mask mistakes fail right at the call instead of one reduction later — with a consistent, searchable error message. See contract failures.

bold.series_roi(roi)

Receipts that travel

Typed results carry a content-addressable Receipt. to_nibabel() embeds it as a NIfTI comment extension and read_image() rehydrates it — recoverable with ten lines of nibabel, no sidecar.

result.provenance

One voxel protocol

Dense, sparse, memory-mapped, and file-backed 4-D containers answer the same calls. Analysis code is identical whether the data is in RAM, on disk, or one volume per file — a public conformance contract.

series_roi · temporal_snr

How to read these docs

  • Start — a five-page on-ramp, each page centered on one practical task. About thirty minutes end-to-end.
  • Concepts — the vocabulary, one page per idea. What each object is, what it guarantees, what it refuses.
  • Cookbook — task-driven recipes, each with the trapdoors that the contracts close.
  • Spec — public contracts written so a third party could implement against them without importing neuroim.
  • Reference — generated API surface, grouped by task.

Every claim above is backed by a runnable scenario. The Evidence page is rebuilt from those scenarios each time the docs are built, so it stays in step with the code.

Back to top