data/extra_parcellation/README.md

Extra Parcellation Data

Provides fine-grained subregion labels alongside the primary Allen atlas meshes.

Setup (recommended)

Run the setup script to build the combined atlas automatically:

python scripts/setup_extra_parcellation.py

This downloads and merges three complementary MNI-space atlases via nilearn:

Layer	Source	Regions	Role
1	Harvard-Oxford Cortical	48	Broad cortical coverage
2	Harvard-Oxford Subcortical	17	Thalamus, putamen, caudate, hippocampus, amygdala, etc.
3	Julich-Brain (highest priority)	62	Cytoarchitectonic: motor BA4a/4p, somatosensory BA1-3, visual V1-V5, auditory, Broca's, hippocampal subfields

Total: 127 labeled regions, Julich-Brain labels override coarser Harvard-Oxford where available.

Output files (auto-detected by flow mode):

• combined_atlas.nii.gz — NIfTI volume (~700KB)
• combined_atlas_labels.json — label ID to name map

How it works

The combined atlas is in MNI152 1mm space. The Allen atlas scene space is approximately MNI-aligned, so probe coordinates can be used directly for lookups. When the exact voxel is unlabeled, a nearby-search fallback finds the closest labeled region within a few mm.

When both the primary Allen mesh and the extra parcellation cover a probe position, both are highlighted: the Allen mesh in red, the extra parcellation subregion in orange. The subregion name is included in the LLM context as additional detail.

Custom atlas

You can also provide any NIfTI atlas in MNI space:

python examples/flow_probe_example.py \
    --extra-parcellation my_atlas.nii.gz \
    --extra-parcellation-labels my_atlas_labels.json

Requirements

pip install nilearn nibabel scikit-image