TUBA — Transcranial Ultrasound Brain Atlas

A unified pipeline for registering skull microCT volumes to brain atlases for transcranial ultrasound simulation, supporting mouse, macaque, human, and rat species under a single library.

from tuba.species import mouse, macaque, human, rat

c, rho, dz, frame = rat.load_slab()  # or mouse / macaque / human

The library handles orientation, downsampling, cavity / outer-bone-surface extraction, ANTs Affine/SyN registration to the species-appropriate atlas, intensity-to-acoustic-property mapping, and beam-aligned slab sampling.

What TUBA gives you

Species	Skull source	Native pitch	Brain atlas	Cavity volume	Report
Mouse	Maga 4K microCT (UW)	6.13 µm	Allen CCFv3 (25 µm, 668 regions)	0.45 mL	PDF
Macaque	AMNH M-87264 (Copes 2016)	60.6 µm	NMT v2 + CHARM / SARM / D99	88 mL	PDF
Human	Halle Zenodo (Kirchner 2022)	125 µm	MNI152 + 6 parcellations	~1300 mL	PDF
Rat	DigiMorph TMM M-2272	29.6 µm	WHS SD v4.01 (Kleven 2023, 222 labels)	2.39 mL	PDF

Two-page overview PDF: docs/overview/summary.pdf

Atlas warped into skull space — one figure per pillar

Mouse — Allen CCFv3 in Maga skull

Macaque — NMT v2 in AMNH M-87264 skull

Human — MNI152 + parcellations in Halle skull

Rat — WHS v4.01 in DigiMorph TMM M-2272 skull

Each species ships:

• a tuba.species.<x> module with the species-specific numerics (voxel size, bone thresholds, closing radii, intensity-ramp endpoints) plus thin wrappers over tuba.core.{cavity, surface, slab, placement, warp},
• a tuba.atlases.<atlas> binding that points at the cached template
  • annotation files and exposes named target / EEG dicts (human: 52 MNI anatomical targets + 22 EEG 10-20 sites),
• a tuba.data.sources manifest entry describing where the raw data comes from (DOI, license, fetcher script).

Six volumetric parcellations are bundled for the human pipeline (Harvard-Oxford, Schaefer 400/1000, AAL3, Pauli 2017 subcortex, Yeo-7 networks) — see docs/human/manuscript.pdf.

Install

Recommended: uv for fast, reproducible installs (pinned by uv.lock):

uv sync                     # installs into a managed .venv
uv sync --extra viz         # + nilearn + plotly
uv sync --extra dev         # + pytest + ruff

If you prefer pip:

pip install -e .
pip install -e ".[viz]"     # nilearn + plotly for richer figures
pip install -e ".[dev]"     # pytest + ruff

Python ≥ 3.10. Core deps: numpy, scipy, nibabel, pynrrd, tifffile, scikit-image, antspyx, matplotlib. antspyx is the heaviest install; on Linux an antspyx wheel covers x86_64. For ARM / macOS use the upstream ANTsPy build instructions.

Data — TUBA_*_REG_DIR env vars

TUBA never bundles raw skull microCT or atlas templates — those are large, sometimes licensed, and each user is expected to stage them locally. The library reads paths from environment variables, falling back to ~/.cache/tuba/<species>/ if unset:

Env var	Purpose
TUBA_MOUSE_REG_DIR	Mouse cache + Allen CCFv3 atlas dir
TUBA_MOUSE_SOURCE_DIR	Raw Maga 4K TIFF stack
TUBA_HUMAN_REG_DIR	Human cache + MNI152 warp transforms
TUBA_HUMAN_NRRD_PATH	Halle skull NRRD source

The full data manifest lives in src/tuba/data/sources.toml, with one entry per dataset (DOI, fetcher script, license, voxel size, expected size). Load it programmatically:

from tuba.data import all_sources, get
for s in all_sources():
    print(s.key, s.license, s.voxel_size_mm)
src = get('mouse.skull')
print(src.source_url, src.fetcher_script)

Fetchers

Every dataset has a fetcher script in src/tuba/data/fetch_*.py. Direct-fetch sources (Allen, NMT, Zenodo) run end-to-end without interaction; click-through or login-required sources print instructions and a drop location, then re-run to unpack.

Fetcher	Hosts	Auth
fetch_mouse.py	Maga (UW) Box	click-through
fetch_allen.py	Allen Institute HTTP	none
fetch_macaque.py	MorphoSource (MCZ)	login + per-record approval
fetch_nmt.py	AFNI / NIMH HTTP	none
fetch_human.py	Zenodo (Kirchner 2022)	none (HALLE_FETCH_ALL=1 for the ~10 GB projection archives)

Integrity

Distribution archives have SHA-256 sums pinned in the manifest (archive_sha256 for tarballs/zips, sha256 for single files). Get the canonical sum list from the manifest:

from tuba.data import integrity_lines
for line in integrity_lines():
    print(line)

Pin a new sum when you stage a fresh dataset:

sha256sum dry_skull_4K_6.125micron_Rec.zip   # compute
# then update sources.toml: archive_sha256 = "..."

Documentation

Per-species validation manuscripts live in docs/:

• docs/mouse/manuscript.pdf — Migrating the 15 MHz transcranial mouse pipeline from DigiMouse to the Maga (UW) 4K microCT (18 pages, includes focal-prediction comparison vs the DigiMouse baseline).
• docs/macaque/manuscript.pdf — AMNH macaque microCT + NMT v2 registration (9 pages, in progress).
• docs/human/manuscript.pdf — MNI152 → Halle dry-skull microCT pipeline (16 pages, six figures, six parcellation atlases catalogued and warped).

Each manuscript follows the same section template (source data → orientation → downsampling → pre-alignment → cavity/surface → SyN → acoustic-property mapping → placement → slab → lessons). See docs/README.md for the section-parity table across species.

Tests

pytest tests/

The regression tests verify that the TUBA port produces outputs bit-identical (or near-bit-identical, accounting for documented mirror behaviour in the human case) to the legacy pipelines they were ported from. They skip automatically if the legacy paths are not locally present — set TUBA_LEGACY_MOUSE_REG and TUBA_LEGACY_HUMAN_REG to run them.

Citation

If TUBA is useful in your work, please cite the species manuscript that matches your application (see docs/<species>/manuscript.pdf) and the underlying atlas (Allen CCFv3 / NMT v2 / MNI152 ICBM 2009a). The full list of dataset citations is in NOTICE.

License

MIT — see LICENSE. The MIT license covers TUBA's source code only.

Data & attribution: TUBA bundles no scans or atlases — it fetches them, and each dataset carries its own license and citation terms (some non‑commercial). Full attributions are in NOTICE; machine‑readable provenance (DOI, license, source URL per dataset) is in src/tuba/data/sources.toml. You must observe each dataset's terms in addition to TUBA's MIT license.