Reproducing the Paper

Reproducing the Paper

The paper_figs/ directory holds the scripts that regenerate every figure in the golgi papers, plus the tooling that packages the figure simulations as replay-verified study bundles for the Zenodo deposit.

Two reproduction paths

There are two ways to reproduce the paper, consuming different files in the same Zenodo record — don't confuse them:

Path	Command	Needs	Download
Verify / quick-look a study (light)	golgi replay <bundle> · golgi figure <bundle>	one study bundle (~50–650 MB each)	python paper_figs/fetch_bundles.py
Regenerate a composite figure (full)	python paper_figs/make_figures.py	the full working dataset (~27 GB)	the working-dataset archive, extracted at the repo root

A study bundle (fig06_human_cervical_vagus.golgi.zip) is a self-contained golgi project (mesh, FEM, fibers, sweeps, audit) that golgi replay/golgi figure consume directly — it is not what make_figures.py reads. The composite figure scripts read the raw working tree (paper_figs/out/data, paper_figs/out/_intermediate, and results_golgi/duke_meshes): meshes, FEM fields, threshold .npz, and cel-shaded renders.

Light path — verify / quick-look (study bundles)

python paper_figs/fetch_bundles.py          # download + checksum-verify all bundles from Zenodo
golgi replay paper_figs/out/zenodo_bundles/fig06_human_cervical_vagus.golgi.zip   # verify byte-for-byte
golgi figure paper_figs/out/zenodo_bundles/fig06_human_cervical_vagus.golgi.zip --out ./figs   # quick-look panels

Bundles are archived at doi.org/10.5281/zenodo.21300944 — a concept DOI that always resolves to the latest version (fetch_bundles.py follows it there; --only fig06 fetches one, --list previews).

Quick-look ≠ paper figure. golgi figure renders golgi's built-in result figures (a threshold-vs-diameter scatter + a Vₑ field slice) from a bundle — not the multi-panel composite figures. For those, use the full path below.

Full path — regenerate the composite figures (working dataset)

The composite multi-panel figures are rebuilt by make_figures.py from the ~27 GB working dataset, which ships in the same Zenodo record as the study bundles (one combined deposit). Download golgi_paper_dataset.tar.gz and extract it at the repo root so the trees land in place, then run the driver:

# from the repo root:
tar xzf paper_figs/out/zenodo_bundles/golgi_paper_dataset.tar.gz         # -> paper_figs/out/{data,_intermediate,renders} + results_golgi/duke_meshes
tar xzf paper_figs/out/zenodo_bundles/golgi_comsol_handover.tar.gz       # -> comsol_handover/  (Figure 4 COMSOL cross-validation panels)
python paper_figs/make_figures.py          # all figures  (or: fig06, fig05 fig08, …)

The dataset is in the same record as the bundles — doi.org/10.5281/zenodo.21300944 (python paper_figs/fetch_bundles.py --only golgi_paper_dataset fetches just the tarball). Each script writes its figure to paper_figs/out/figures/{png,pdf,svg}/. ROOT resolves from the GOLGI_PAPER_ROOT environment variable or, unset, the repo root — so if you keep the dataset elsewhere, point it there: GOLGI_PAPER_ROOT=/path/to/tree python paper_figs/make_figures.py. If the dataset is absent, make_figures.py fails fast with these instructions rather than deep inside a figure script.

---

Figure → script map

The authoritative mapping is the output filename each script writes (docstring figure numbers in a few files lag a mid-draft renumbering — trust the filenames) and the curated KEEP_PAPERFIGS allowlist in make_release_package.py.

Script names follow the paper's figure numbers (fig0N_*). Run one, several, or all via the driver:

python paper_figs/make_figures.py            # all figures
python paper_figs/make_figures.py fig07      # just Fig 7
python paper_figs/make_figures.py fig05 fig08

Each writes its multi-panel figure to paper_figs/out/figures/{png,pdf,svg}/ and needs the full intermediate dataset — this is not driven by a study bundle (a bundle carries one config's slice, which the golgi figure CLI renders as a quick-look, not the composite figure).

Figure	Script(s)	Content · species
Fig 2	fig02_setup.py, fig02_render.py	Modeling setup & FEM solution (cuff, multi-region mesh, cuff-designer, Vₑ & |E| cross-sections, along-fiber Vₑ + activating function) · swine
Fig 4	fig04_validation.py (assembles comsol_validation_fig, validate_fig, fig_nrv, fig_bucksot)	Integrated validation: analytic/COMSOL, dog-VNS, NRV LIFE, Bucksot
Fig 5	fig05_06_species.py (+ fig5_population.py, fig5_thresholds.py, fig06_selectivity.py)	7-panel per-species result · swine cervical vagus
Fig 6	fig05_06_species.py (human half — one run produces Fig 5 and Fig 6)	7-panel per-species result · human cervical vagus
Fig 7	fig07_rabbit_selectivity.py	Superior-cardiac-branch-selective stim, 4×5 ring cuff + position×config sweep · real-3-D rabbit
Fig 8	fig08_human_selectivity.py	SCB-selective stim, 4×5 ring cuff + position×config sweep · real-3-D human

Supplements / tables: validate_fig.py (→ supp_foundations, the S8 fiber-model foundations), validate_mrg.py (MRG vs McIntyre discrete), comsol_validation_fig.py (→ supp_comsol_validation, S15), fig_supp_cohort.py (cohort gallery), cohort_table.py + gen_s1_table.py (the S1 cohort table). Rendering scripts (render_*.py) make the cel-shaded PyVista presentation renders.

Per-figure pipelines

Each species result is produced by a sequence of pipeline-driver scripts that mesh, solve, seed fibers, and sweep — for example the human SCB / Fig 8 chain:

new_human3d_prep → new_human3d_traj → new_human_mesh → new_human_fem
   → new_human_sweep → new_human_tripole_sweep_build → new_human_tripole_analyze
   → new_human_steer_opt → new_human_xsec_contours

with parallel rabbit_* (Fig 7) and human_bundle_* (Fig 6) chains. Threshold sweeps for the selectivity panels run through fig5_thresholds.py (golgi's exact PyFibers/NEURON bisection path) and the run_*_tripole_sweep_thr.sh drivers. Species covered across the paper: swine, human, rabbit, dog (dog-VNS), and cat (NRV LIFE).

Packaging for Zenodo

• make_study_bundles.py packages the Fig 4–8 simulations as hashed, replay-verified .golgi bundles (each re-checked byte-for-byte via golgi.projects.replay) into paper_figs/out/study_bundles/ with a BUNDLES.json + CHECKSUMS.sha256. Bundle IDs: fig04a_dogvns_validation, fig04c_bucksot_validation, fig05_swine_cervical_vagus, fig06_human_cervical_vagus, fig07_rabbit_branching, fig08_human_scb_branching (fig04b NRV-LIFE ships cached figure data, as the synthetic LIFE geometry isn't re-meshable).

  python paper_figs/make_study_bundles.py            # all figures
  python paper_figs/make_study_bundles.py fig07       # one figure

• make_release_package.py assembles the full paper deliverable (both manuscripts, the curated code subset, the reproduction bundles + checksums, and a top-level README). The KEEP_PAPERFIGS list in it (≈lines 53–95) is the definitive index of which script produces which figure.

---

See also

Validation · Reproducible Study Bundles · Pipeline Overview · License & Citation