Allen Human Reference Atlas 3D (2020) — Left/Right Label Split

Generate a left/right hemisphere–labelled version of the Allen Human Reference Atlas 3D (2020) full-brain annotation. Bilateral (paired) structures are split into distinct left and right labels; structures that are unpaired / midline by neuroanatomical convention are kept as a single label.

Before: the distributed annotation_full is mirror-symmetric — both hemispheres share one label per structure. After: paired structures (e.g. thalamus, basal ganglia, cortex) carry separate left/right labels (left hemisphere recoloured); midline structures (ventricles, commissures, vermis, brainstem tegmentum…) are unchanged.

Why

The Allen atlas ships annotation_full.nii.gz, built by mirroring the single-hemisphere annotation across the midline (full = max(annotation, flip_x(annotation))). Every structure therefore has the same label value on both sides — there is no left/right distinction, and the center of mass of every structure sits exactly on the midline. This project adds a proper L/R labelling.

Method

• Midline plane. The atlas lives on the MNI152 ICBM 2009b symmetric template (0.5 mm), so the mid-sagittal plane is world x = 0 (RAS, +x = anatomical right). The plane maps to one exact voxel column; it is assigned to the right side.
• Split. Each voxel left of the plane gets a new left label; right stays.
• Keep-single set is defined by neuroanatomical convention — structures normally named without a side. This is a deliberate choice: a purely geometric test does not work here (the symmetric atlas makes every centroid land on the midline, and commissures that genuinely cross the midline extend far laterally so they look "lateral" to a distance metric).

Kept single (16)

Group	Structures
Ventricular midline	3V third ventricle, 4V fourth ventricle, Aq cerebral aqueduct, cec central canal
Commissures	ac anterior commissure, cc corpus callosum
Other midline	fx fornix, Pin pineal body, CBV cerebellar vermis
Midline thalamic nuclei	MiN midline nuclear complex, Re reuniens nucleus
Septal	SEP septal nuclei
Brainstem midline regions	MTg midbrain tegmentum, PnTg pontine tegmentum, MoTg medullary tegmentum, PnBa basilar pons

Everything else (125 structures) is split L/R: thalamus, hypothalamus, basal ganglia, all cortex, lateral ventricle horns, colliculi, RN/SN/STH/ZI, habenula, pyramids/olive, peduncles & tracts, cerebellar hemisphere / paravermis / deep nuclei, hippocampus, amygdala, forebrain/hindbrain white matter.

Judgment calls: SEP, fx, and the four brainstem regions are midline-continuous regions rather than strictly unpaired (cf. AAL/FreeSurfer, which treat the brainstem as a single label). The keep-single set lives at the top of split_lr.py as KEEP_SINGLE — edit one acronym and rerun (~1 min) to reclassify any structure.

ID scheme

Output space	Right	Left	Midline
ITK-SNAP index	idx	idx + 1000	idx
Native Allen dbID	dbID	dbID + 1e9	dbID

Names are prefixed R- / L-; midline names are unchanged.

Usage

Requires uv, curl, and unzip. Everything else (a Python venv, SimpleITK/numpy/matplotlib, all downloads) is handled by the script:

./run.sh

run.sh is idempotent — downloaded inputs are reused on re-runs. It downloads the Allen annotation + label table and the MNI152 template, runs the split, and regenerates the QC image.

Outputs

All large files are git-ignored (regenerate with ./run.sh); only source and the QC image under images/ are tracked.

File	Description
annotation_full_LR.nii.gz	L/R volume, ITK-SNAP index values (uint16)
itksnap_label_description_Br_LR.txt	matching ITK-SNAP label table (R-/L-, left rows darkened)
annotation_full_LR_dbid.nii.gz	L/R volume, native Allen dbID values (int64)
label_description_Br_LR_dbid.csv	dbID ↔ index ↔ side ↔ acronym table
midline_report.txt	audit: which structures were kept single vs split
images/qc_before_after.png	before/after QC overlay

Load annotation_full_LR.nii.gz with itksnap_label_description_Br_LR.txt in ITK-SNAP.

Verification (asserted in split_lr.py)

• dbID ↔ index mapping is 1:1 with zero unmapped labels.
• Per-label left/right voxel counts are symmetric (mirror construction).
• Round-trip: collapsing every left label back (− offset) reproduces the original index map exactly.

Files

• run.sh — download + build pipeline
• split_lr.py — the L/R split (CLI; KEEP_SINGLE knob at top)
• make_qc.py — before/after QC rendering

Source & attribution

• Allen Human Reference Atlas – 3D, 2020. Allen Institute for Brain Science. community post · data archive
• MNI152 ICBM 2009b Nonlinear Symmetric template — V. Fonov et al., McConnell Brain Imaging Centre, MNI. download