joss paper update

Author: teanijarv

paper/paper.bib

@@ -99,6 +99,17 @@ @article{Hunter:2007
   url       = {https://doi.org/10.1109/MCSE.2007.55}
 }
 
+@article{Chopra:2023,
+  title = {A Practical Guide for Generating Reproducible and Programmatic Neuroimaging Visualizations},
+  author = {Chopra, Siddharth and Labache, Lo{\"i}c and Juh{\'a}sz, Csaba and Iturria-Medina, Yasser and Bellec, Pierre and Misic, Bratislav and Vos de Wael, Reinder and Bernhardt, Boris C. and Valk, Sofie L.},
+  journal = {Aperture Neuro},
+  volume = {3},
+  pages = {1--20},
+  year = {2023},
+  doi = {10.52294/001c.85104},
+  url = {https://doi.org/10.52294/001c.85104}
+}
+
 @article{Marcus:2011,
   title   = {Informatics and Data Mining Tools and Strategies for the Human Connectome Project},
   author  = {Marcus, Daniel S. and Harwell, John and Olsen, Timothy and Hodge, Michael and Glasser, Matthew F. and Prior, Fred and Jenkinson, Mark and Laumann, Timothy and Curtiss, Sandra W. and Van Essen, David C.},
@@ -155,3 +166,12 @@ @article{VosdeWael:2020
   doi     = {10.1038/s42003-020-0794-7},
   url     = {https://doi.org/10.1038/s42003-020-0794-7}
 }
+
+@article{Bryant:2026,
+  title={Subcortex visualization: A toolbox for custom data visualization in the subcortex and cerebellum},
+  author={Bryant, Annie G},
+  journal={bioRxiv},
+  pages={2026--01},
+  year={2026},
+  publisher={Cold Spring Harbor Laboratory}
+}

paper/paper.md

@@ -13,36 +13,50 @@ authors:
 affiliations:
  - name: Clinical Memory Research Unit, Department of Clinical Sciences Malmö, Faculty of Medicine, Lund University, Lund, Sweden
    index: 1
-date: 11 May 2026
+date: 14 May 2026
 bibliography: paper.bib
 ---
 
 # Summary
 
-Neuroimaging analyses often produce results in several anatomical representations. A single study may include values defined in atlas-based regions, such as cortical parcels, subcortical structures, white-matter bundles, or connectivity matrices, as well as continuous voxel-wise and vertex-wise maps. Communicating these results requires figures that are anatomically interpretable, visually consistent, and reproducible from the same computational workflow used to generate the data.
+Neuroimaging analyses often produce results in several anatomical representations. A single study may include values defined in atlas-based regions, such as cortical parcels, subcortical structures, or white-matter bundles, as well as continuous voxel-wise and vertex-wise maps and region-to-region connectivity matrices. Communicating these results requires figures that are anatomically interpretable, visually consistent, and reproducible from the same computational workflow used to generate the data.
 
-`yabplot` (yet another brain plot) is an open-source Python package for creating three-dimensional neuroimaging visualizations across these representations. It provides a unified interface for plotting cortical parcellations, vertex-wise cortical data, voxel-wise volumetric data, subcortical structures, white-matter bundles, tractometry results, and connectome graphs. The package is intended for researchers who want to create publication-ready figures directly from Python scripts or Jupyter notebooks, without switching between multiple specialized graphical applications. Inputs depend on the function, but include NIfTI images, surface files, tractography files, arrays, dictionaries, and matrices, which are mapped to standard or user-defined anatomical resources.
+`yabplot` (yet another brain plot) is an open-source Python package for creating three-dimensional neuroimaging visualizations across these representations. It provides a unified interface for plotting cortical parcellations, vertex-wise cortical data, voxel-wise volumetric data, subcortical structures, white-matter bundles, tractometry results, and connectome graphs. The package is intended for researchers who want to create publication-ready figures directly from Python scripts or Jupyter notebooks, without switching between multiple specialized graphical applications. Supported inputs depend on the plotting function and include NIfTI images, surface files, tractography files, arrays, dictionaries, tabular data, and matrices. These inputs are mapped to standard or user-defined anatomical resources.
 
 The package builds on established scientific Python libraries. It uses `nibabel` for neuroimaging file input/output [@Brett:2024], `numpy` for numerical array operations [@Harris:2020], `pandas` for tabular and labelled data inputs [@McKinney:2010], `scipy` for interpolation, filtering, and sparse matrix operations [@Virtanen:2020], `pooch` for resource retrieval and caching [@Uieda:2020], `scikit-image` for extracting surface meshes from volumetric masks [@vanDerWalt:2014], `pyvista` for three-dimensional mesh representation, scene construction, and rendering [@Sullivan:2019], `trame` for interactive browser-based visualization [@Jourdain:2025], and `matplotlib` for static figure composition and customization [@Hunter:2007]. By combining these tools behind a compact plotting API, `yabplot` handles data mapping, mesh creation, camera placement, lighting, and rendering while retaining compatibility with standard Python plotting workflows.
 
-![Overview of `yabplot` functionality. The package provides utilities for resource access, atlas construction, volume projection, and mesh handling, and high-level plotting functions for cortical parcellations, vertex-wise surface maps, subcortical structures, voxel-wise volumes, white-matter tracts, and connectome graphs.](figures/overview_joss.pdf)
+![Overview of `yabplot` functionality. The package provides utilities for resource access, atlas construction, volume projection, and mesh handling, together with high-level plotting functions for cortical parcellations, vertex-wise surface maps, subcortical structures, voxel-wise volumes, white matter tracts, and connectome graphs.](figures/overview_joss.pdf)
 
 # Statement of need
 
+Researchers working with neuroimaging data often need to communicate results across several anatomical representations, including cortical regions, vertex-wise maps, subcortical structures, voxel-wise maps, white matter tracts, and connectivity matrices [@Chopra:2023]. The target users of `yabplot` are neuroimaging researchers and students who want to generate consistent 3D figures directly in Python-based data analysis workflows.
+
+Producing such figures can be difficult when each representation requires a different application or plotting library. Switching between tools can require data conversion, manual screenshot-based workflows, and repeated adjustment of lighting, camera angles, colormaps, and output formatting. `yabplot` addresses this need by providing a unified, scriptable interface for common 3D neuroimaging visualizations, with consistent styling and output handling across modalities.
+
+# State of the field
+
 The neuroimaging visualization ecosystem includes many mature and widely used tools. Connectome Workbench supports surface-based visualization and Human Connectome Project resources [@Marcus:2011], MRtrix3 provides diffusion MRI processing and tractography visualization [@Tournier:2019], and BrainNet Viewer supports graph-based visualization of human connectomes [@Xia:2013]. In Python, Nilearn provides accessible statistical neuroimaging visualization, especially for slice-based, glass-brain, and machine-learning workflows [@Abraham:2014], while BrainSpace supports surface-based visualization in the context of macroscale gradients and connectomics [@VosdeWael:2020].
 
-These tools cover important parts of the visualization workflow, but producing a coherent figure that combines different representations of neuroimaging data can still require several packages or applications. This introduces practical barriers. Researchers may need to translate data between different input conventions; manual screenshot-based workflows make figure generation harder to reproduce; and differences in lighting style and camera perspective can make results appear visually inconsistent within the same research study.
+These tools cover important parts of the visualization workflow, but they are often specialized for one representation or analysis domain. Rather than replacing these packages, `yabplot` provides a complementary layer focused on consistent, publication-oriented 3D figure generation across cortical, subcortical, tractography, voxel-wise, and connectome data. This unified focus is the main reason for building a new package rather than contributing a modality-specific feature to an existing tool.
+
+# Software design
+
+`yabplot` is organized around high-level plotting functions that share common utilities for data mapping, mesh handling, camera presets, color handling, background anatomy, and output generation. This design trades some low-level rendering flexibility for consistency and ease of use across modalities. Users provide data values and an anatomical target, choose views and visual styling, and receive a rendered static figure or interactive object.
+
+A further design goal is to separate the Python package from large anatomical resources. Supported atlases, meshes, and tract resources are retrieved on demand and cached locally, keeping the core installation lightweight while making resource use explicit. The package also supports custom user-defined anatomical resources through atlas-building and mesh-construction utilities, allowing users to adapt the workflow to study-specific parcellations, segmentations, and tractography datasets rather than being limited to bundled templates.
+
+# Research impact
 
-`yabplot` addresses this gap by focusing on unified, scriptable, publication-oriented 3D rendering of common neuroimaging result types within a single Python environment. Its plotting functions follow a shared pattern: users provide data values and an anatomical target, choose views and visual styling, and receive a rendered figure or interactive object. High-level functions are provided for regional cortical data (`plot_cortical`), vertex-wise cortical data (`plot_vertexwise`), voxel-wise volumes (`plot_voxelwise`), subcortical structures (`plot_subcortical`), white-matter bundles (`plot_tracts`), and connectivity matrices (`plot_connectome`). These functions share common building blocks for data mapping, mesh construction, camera presets, color handling, background anatomy for context, and output generation, while still exposing modality-specific options where needed.
+`yabplot` is designed to support reproducible figure generation in neuroimaging projects that combine several anatomical representations. The package is publicly available on PyPI, documented with example workflows, archived with a Zenodo DOI, and tested through continuous integration. Early user feedback has informed support for Matplotlib-compatible customization, custom atlas generation, and expanded plotting functionality.
 
-A further design goal is to separate the Python package from large anatomical resources. `yabplot` retrieves supported atlases, meshes, and tract resources on demand and caches them locally, keeping the core installation lightweight while making resource use explicit. The package also supports custom user-defined anatomical resources through atlas-building and mesh-construction utilities, allowing users to adapt the workflow to study-specific parcellations, segmentations, and tractography datasets. By bringing these visualization tasks into a consistent interface, the package lowers the technical barrier to high-quality 3D neuroimaging figures and supports reproducible scientific communication.
+Beyond standalone figure generation, `yabplot` is already used by the external `subcortex_visualization` package [@Bryant:2026], where its atlas-building and rendering utilities support a semi-automated workflow for converting volumetric segmentations into SVG-based custom atlas visualizations. These community-readiness signals provide a foundation for near-term use in neuroimaging studies requiring consistent 3D visualization across modalities.
 
 # AI usage disclosure
 
-Generative AI models have been utilized in the development process of `yabplot` and in the drafting of this manuscript. The author reviewed and verified all AI-generated content.
+Generative AI tools, including ChatGPT and Gemini, were used during the development of `yabplot` and preparation of this manuscript. They were used for code refactoring suggestions, debugging assistance, documentation drafting, and manuscript outlining. The author reviewed, edited, and verified all AI-assisted code, documentation, and manuscript text, and takes full responsibility for the submitted software and manuscript.
 
 # Acknowledgements
 
-The author would like to thank the early contributors, including Anthony J Barrows, Jannis Denecke, and Anthony Gagnon, for their valuable code improvements and feedback during the development of this package. `yabplot` relies on the work of the broader neuroimaging and scientific Python communities, including the developers and maintainers of `nibabel`, `numpy`, `scipy`, `pandas`, `pyvista`, `trame`, `matplotlib`, `pooch`, `scikit-image`, and the atlas resources supported by the package. Users should cite the original publications for any atlases used in their analyses.
+The author would like to thank the early contributors, including Anthony J. Barrows, Jannis Denecke, and Anthony Gagnon, for their valuable code improvements and feedback during the development of this package. `yabplot` relies on the work of the broader neuroimaging and scientific Python communities, including the developers and maintainers of `nibabel`, `numpy`, `scipy`, `pandas`, `pyvista`, `trame`, `matplotlib`, `pooch`, `scikit-image`, and the atlas resources supported by the package. Users should cite the original publications for any atlases used in their analyses.
 
 # References