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:

```bash
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:

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

## Requirements

```bash
pip install nilearn nibabel scikit-image
```