Codex skill for reproducible subcortical and cerebellar ROI visualization, built around Annie Bryant's subcortex_visualization package with Python/R-friendly workflows.
Locally reproduced atlas showcase generated by this skill; empirical workflows replace atlas-index colours with your ROI values.
This repository contains an interactive Codex skill for reproducible two-dimensional visualization of subcortical, thalamic, brainstem, and cerebellar ROI data. It turns a common neuroimaging pain point — "I have ROI values, but no clean, consistent subcortical figure workflow" — into a checked sequence of backend choice, environment diagnostics, atlas selection, table validation, NIfTI parcel extraction, figure export, and Methods/caption provenance.
This repository is an agent skill layer, not a fork or replacement of the original toolbox. It does not vendor the original package, paper PDF, or downloaded source archive.
- Choose Python or R before plotting.
- Check missing dependencies before running code.
- Select a supported subcortical/cerebellar atlas.
- Validate ROI tables against atlas region names.
- Extract ROI summaries from MNI-space NIfTI maps.
- Render editable SVG/PDF figures, with PNG previews when useful.
- Keep subcortex, thalamus, brainstem, and cerebellum figures in one flat, publication-oriented visual language.
- Write concise Methods, captions, and provenance notes.
- Plan custom segmentation-to-SVG atlas workflows.
Cortical maps are often easy to communicate because common 2D atlas schematics are already part of the field's visual vocabulary. Subcortical and cerebellar results are harder: figures can quickly become a mix of screenshots, slice views, inconsistent palettes, and ad-hoc labels.
This skill packages a more reproducible route. It keeps atlas names explicit, validates every ROI label before plotting, produces editable vector outputs, and records enough provenance for a Methods section or supplementary workflow note.
The hero image is generated locally with this repository. It is not copied from the upstream documentation.
python subcortex-visualization/scripts/make_all_atlas_showcase.py --output assets/gallery/all_atlas_showcase.pngThe skill supports both Python and R workflows: Python is best for NIfTI/MNI-space pipelines, while R is best for tidyverse, patchwork, and ggseg-style composites.
After installing the underlying subcortex_visualization package, validate and plot the bundled demo ROI table:
python subcortex-visualization/scripts/check_subcortex_environment.py --backend python
python subcortex-visualization/scripts/validate_subcortex_table.py \
--input subcortex-visualization/assets/examples/thalamus_thomas_demo.csv \
--atlas Thalamus_THOMAS \
--value-column value
python subcortex-visualization/scripts/plot_subcortex_table.py \
--input subcortex-visualization/assets/examples/thalamus_thomas_demo.csv \
--output-prefix demo/thalamus_thomas_demo \
--atlas Thalamus_THOMAS \
--value-column value \
--hemisphere both \
--formats png,svgThe demo writes preview files under demo/, which is ignored by git.
Copy the skill folder into your Codex skills directory:
subcortex-visualization/
Then ask Codex, for example:
Use the subcortex-visualization skill. I have a ROI table and want to plot a thalamus map.
For a first test without real data:
Use the subcortex-visualization skill. Generate simulated thalamus ROI data and make a preview figure.
The skill follows a compact figure-design loop that mirrors the companion cortex skill:
backend -> environment check -> figure contract -> atlas/region validation -> preview/export -> QC -> revision
The first question is usually:
Do you want to use Python or R?
Python is better for NIfTI/Python neuroimaging pipelines. R is better for tidyverse, patchwork, and ggseg-style composite figures. The goal is not merely to make a pretty brain icon; the goal is to make a figure that can be checked, regenerated, and explained.
- White background.
- Matte atlas fills with clear outlines.
- Conservative diverging or sequential colour scales.
- SVG/PDF as primary outputs; PNG as quick preview.
- Atlas and ROI names reported explicitly.
- No hidden smoothing, relabelling, or biological over-interpretation.
The skill includes a diagnostic helper:
python subcortex-visualization/scripts/check_subcortex_environment.py --backend bothIt checks Python packages such as numpy, pandas, matplotlib, svgpath2mpl, nibabel, nilearn, and subcortex_visualization, and R availability through Rscript plus key R packages. If packages are missing, the skill reports the blocker and asks before installing anything.
subcortex-visualization/
|-- SKILL.md
|-- agents/
| `-- openai.yaml
|-- assets/
| `-- examples/
| `-- thalamus_thomas_demo.csv
|-- references/
| |-- atlas_catalog.md
| |-- environment_setup.md
| |-- interactive_workflow.md
| |-- r_usage.md
| `-- ...
`-- scripts/
|-- check_subcortex_environment.py
|-- extract_subcortex_segstats.py
|-- inspect_subcortex_atlas.py
|-- make_all_atlas_showcase.py
|-- plot_subcortex_table.py
`-- validate_subcortex_table.py
The skill treats each figure as a visual argument, not a decorative brain icon. It prefers exact atlas names, validated region labels, conservative color scales, editable vector outputs, and explicit provenance.
This skill was written from public materials for Annie Bryant's subcortex_visualization project, including the project documentation, preprint, and source code. Build-only local materials are ignored and are not intended to be pushed to GitHub.
This skill is built around Annie Bryant's subcortex_visualization toolbox. If you use the underlying toolbox or its visualizations, please cite the original work:
Bryant, A. G. (2026). Subcortex visualization: A toolbox for custom data visualization in the subcortex and cerebellum. bioRxiv. https://www.biorxiv.org/content/10.64898/2026.01.23.699785