more tests + joss manuscript

Author: teanijarv

.github/workflows/tests.yml

@@ -20,10 +20,7 @@ jobs:
     - name: Cache downloaded data
       uses: actions/cache@v4
       with:
-        # The folder where pooch saves files on Linux
         path: ~/.cache/yabplot
-        # Check registry.txt to decide if we need a fresh download
-        # (using **/ finds the file even if your folder structure varies)
         key: yabplot-data-${{ hashFiles('**/registry.txt') }}
         restore-keys: |
           yabplot-data-
@@ -33,21 +30,18 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    # 1. Install System Libraries for 3D Graphics (Headless)
     - name: Install system dependencies (Linux)
       run: |
         sudo apt-get update
         sudo apt-get install -y libgl1 xvfb
 
-    # 2. Install your package and testing tools
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install pytest
         pip install ".[docs]"  # Installs yabplot + deps
 
-    # 3. Run Pytest inside a virtual monitor
     - name: Run tests
       run: |
         # xvfb-run allows graphical apps to run without a real monitor
-        xvfb-run -a pytest
+        PYTHONPATH=. xvfb-run -a pytest tests/

.gitignore

@@ -5,18 +5,18 @@ examples_/
 docs/tutorials/tutorial_data/
 dev/
 site/
-paper/
-paperprep/
 tutorial_data/
 test.ipynb
 todo.md
 test_data/
 # *.ipynb
 test.py
+# paper/figures/
 
 .DS_Store
 __pycache__/
 .venv
+.pytest_cache/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

paper/figures/overview_joss.pdf

@@ -0,0 +1,157 @@
+@software{Brett:2024,
+  title     = {nipy/nibabel: 5.3.2},
+  author    = {Brett, Matthew and Markiewicz, Christopher J. and Hanke, Michael and C{\^o}t{\'e}, Marc-Alexandre and Cipollini, Ben and McCarthy, Paul and Ghosh, Satrajit and Wassermann, Demian and Halchenko, Yaroslav O. and Forbes, Jessica and others},
+  year      = {2024},
+  publisher = {Zenodo},
+  version   = {5.3.2},
+  doi       = {10.5281/zenodo.17833216},
+  url       = {https://doi.org/10.5281/zenodo.17833216}
+}
+
+@article{Harris:2020,
+  title   = {Array programming with {NumPy}},
+  author  = {Harris, Charles R. and Millman, K. Jarrod and van der Walt, St{\'e}fan J. and Gommers, Ralf and Virtanen, Pauli and Cournapeau, David and Wieser, Eric and Taylor, Julian and Berg, Sebastian and Smith, Nathaniel J. and Kern, Robert and Picus, Matti and Hoyer, Stephan and van Kerkwijk, Marten H. and Brett, Matthew and Haldane, Allan and del R{\'i}o, Jaime Fern{\'a}ndez and Wiebe, Mark and Peterson, Pearu and G{\'e}rard-Marchant, Pierre and Sheppard, Kevin and Reddy, Tyler and Weckesser, Warren and Abbasi, Hameer and Gohlke, Christoph and Oliphant, Travis E.},
+  journal = {Nature},
+  volume  = {585},
+  pages   = {357--362},
+  year    = {2020},
+  doi     = {10.1038/s41586-020-2649-2},
+  url     = {https://doi.org/10.1038/s41586-020-2649-2}
+}
+
+@article{Virtanen:2020,
+  title   = {{SciPy} 1.0: Fundamental Algorithms for Scientific Computing in Python},
+  author  = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and van der Walt, St{\'e}fan J. and Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and Kern, Robert and Larson, Eric and Carey, C. J. and Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and VanderPlas, Jake and Laxalde, Denis and Perktold, Josef and Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and Harris, Charles R. and Archibald, Anne M. and Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and van Mulbregt, Paul and SciPy 1.0 Contributors},
+  journal = {Nature Methods},
+  volume  = {17},
+  pages   = {261--272},
+  year    = {2020},
+  doi     = {10.1038/s41592-019-0686-2},
+  url     = {https://doi.org/10.1038/s41592-019-0686-2}
+}
+
+@inproceedings{McKinney:2010,
+  title     = {Data Structures for Statistical Computing in Python},
+  author    = {McKinney, Wes},
+  journal   = {SciPy 2010},
+  year      = {2010},
+  doi       = {10.25080/Majora-92bf1922-00a},
+  url       = {https://doi.org/10.25080/Majora-92bf1922-00a}
+}
+
+@article{Uieda:2020,
+  title     = {Pooch: A friend to fetch your data files},
+  author    = {Uieda, Leonardo and Soler, Santiago Rub{\'e}n and Rampin, R{\'e}mi and van Kemenade, Hugo and Turk, Matthew and Shapero, Daniel and Banihirwe, Anderson and Leeman, John R.},
+  journal   = {Journal of Open Source Software},
+  volume    = {5},
+  number    = {45},
+  pages     = {1943},
+  year      = {2020},
+  publisher = {The Open Journal},
+  doi       = {10.21105/joss.01943},
+  url       = {https://doi.org/10.21105/joss.01943}
+}
+
+@article{vanDerWalt:2014,
+  title   = {scikit-image: image processing in Python},
+  author  = {van der Walt, St{\'e}fan and Sch{\"o}nberger, Johannes L. and Nunez-Iglesias, Juan and Boulogne, Fran{\c{c}}ois and Warner, Joshua D. and Yager, Neil and Gouillart, Emmanuelle and Yu, Tony and the scikit-image contributors},
+  journal = {PeerJ},
+  volume  = {2},
+  pages   = {e453},
+  year    = {2014},
+  doi     = {10.7717/peerj.453},
+  url     = {https://doi.org/10.7717/peerj.453}
+}
+
+@article{Sullivan:2019,
+  title     = {{PyVista}: {3D} plotting and mesh analysis through a streamlined interface for the {Visualization Toolkit} ({VTK})},
+  author    = {Sullivan, C. Bane and Kaszynski, Alexander A.},
+  journal   = {Journal of Open Source Software},
+  volume    = {4},
+  number    = {37},
+  pages     = {1450},
+  year      = {2019},
+  publisher = {The Open Journal},
+  doi       = {10.21105/joss.01450},
+  url       = {https://doi.org/10.21105/joss.01450}
+}
+
+@software{Jourdain:2025,
+  title     = {Kitware/trame: v3.10.0},
+  author    = {Jourdain, Sebastien and Avery, Patrick and Finet, Julien and Bhasin, Krishan and Harris, Chris and Bourdais, Jules and Vrabec, Karel and Macron, Lucie and others},
+  year      = {2025},
+  publisher = {Zenodo},
+  version   = {v3.10.0},
+  doi       = {10.5281/zenodo.15540324},
+  url       = {https://doi.org/10.5281/zenodo.15540324}
+}
+
+@article{Hunter:2007,
+  title     = {Matplotlib: A 2D Graphics Environment},
+  author    = {Hunter, John D.},
+  journal   = {Computing in Science \& Engineering},
+  volume    = {9},
+  number    = {3},
+  pages     = {90--95},
+  year      = {2007},
+  publisher = {IEEE Computer Society},
+  doi       = {10.1109/MCSE.2007.55},
+  url       = {https://doi.org/10.1109/MCSE.2007.55}
+}
+
+@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.},
+  journal = {Frontiers in Neuroinformatics},
+  volume  = {5},
+  pages   = {4},
+  year    = {2011},
+  doi     = {10.3389/fninf.2011.00004},
+  url     = {https://doi.org/10.3389/fninf.2011.00004}
+}
+
+@article{Tournier:2019,
+  title   = {{MRtrix3}: A fast, flexible and open software framework for medical image processing and visualisation},
+  author  = {Tournier, J.-D. and Smith, Robert E. and Raffelt, David and Tabbara, Rami and Dhollander, Thijs and Pietsch, Maximilian and Christiaens, Daan and Jeurissen, Ben and Yeh, Chun-Hung and Connelly, Alan},
+  journal = {NeuroImage},
+  volume  = {202},
+  pages   = {116137},
+  year    = {2019},
+  doi     = {10.1016/j.neuroimage.2019.116137},
+  url     = {https://doi.org/10.1016/j.neuroimage.2019.116137}
+}
+
+@article{Xia:2013,
+  title   = {BrainNet Viewer: A Network Visualization Tool for Human Brain Connectomics},
+  author  = {Xia, Mingrui and Wang, Jinhui and He, Yong},
+  journal = {PLOS ONE},
+  volume  = {8},
+  number  = {7},
+  pages   = {e68910},
+  year    = {2013},
+  doi     = {10.1371/journal.pone.0068910},
+  url     = {https://doi.org/10.1371/journal.pone.0068910}
+}
+
+@article{Abraham:2014,
+  title   = {Machine learning for neuroimaging with scikit-learn},
+  author  = {Abraham, Alexandre and Pedregosa, Fabian and Eickenberg, Michael and Gervais, Philippe and Mueller, Andreas and Kossaifi, Jean and Gramfort, Alexandre and Thirion, Bertrand and Varoquaux, Ga{\"e}l},
+  journal = {Frontiers in Neuroinformatics},
+  volume  = {8},
+  pages   = {14},
+  year    = {2014},
+  doi     = {10.3389/fninf.2014.00014},
+  url     = {https://doi.org/10.3389/fninf.2014.00014}
+}
+
+@article{VosdeWael:2020,
+  title   = {{BrainSpace}: a toolbox for the analysis of macroscale gradients in neuroimaging and connectomics datasets},
+  author  = {Vos de Wael, Reinder and Benkarim, Oualid and Paquola, Casey and Lariviere, Sara and Royer, Jessica and Tavakol, Shahin and Xu, Ting and Hong, Seok-Jun and Langs, Georg and Valk, Sofie L. and Mi{\v{s}}i{\'c}, Bratislav and Milham, Michael P. and Margulies, Daniel S. and Smallwood, Jonathan and Bernhardt, Boris C.},
+  journal = {Communications Biology},
+  volume  = {3},
+  number  = {1},
+  pages   = {103},
+  year    = {2020},
+  doi     = {10.1038/s42003-020-0794-7},
+  url     = {https://doi.org/10.1038/s42003-020-0794-7}
+}

paper/paper.bib

@@ -0,0 +1,48 @@
+---
+title: 'yabplot: yet another brain plot for unified neuroimaging visualization in Python'
+tags:
+  - Python
+  - neuroimaging
+  - visualization
+  - neuroscience
+  - 3D
+authors:
+  - name: Toomas Erik Anijärv
+    orcid: 0000-0002-3650-4230
+    affiliation: 1
+affiliations:
+ - name: Clinical Memory Research Unit, Department of Clinical Sciences Malmö, Faculty of Medicine, Lund University, Lund, Sweden
+   index: 1
+date: 11 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.
+
+`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.
+
+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)
+
+# Statement of need
+
+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.
+
+`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.
+
+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.
+
+# 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.
+
+# 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.
+
+# References

paper/paper.md

@@ -0,0 +1,51 @@
+import pytest
+import numpy as np
+import nibabel as nib
+import pyvista as pv
+
+pv.OFF_SCREEN = True
+
+@pytest.fixture
+def synthetic_nifti(tmp_path):
+    """Generates a simple 3D NIfTI file with a sphere of high intensity."""
+    shape = (20, 20, 20)
+    data = np.zeros(shape)
+
+    # create a simple sphere
+    cz, cy, cx = 10, 10, 10
+    r = 5
+    z, y, x = np.ogrid[:shape[0], :shape[1], :shape[2]]
+    mask = (z - cz)**2 + (y - cy)**2 + (x - cx)**2 <= r**2
+    data[mask] = 10.0
+
+    affine = np.eye(4)
+    img = nib.Nifti1Image(data, affine)
+    file_path = tmp_path / "synthetic.nii.gz"
+    nib.save(img, file_path)
+    return str(file_path)
+
+@pytest.fixture
+def synthetic_nifti_4d(tmp_path):
+    """Generates a 4D NIfTI file."""
+    shape = (20, 20, 20, 3)
+    data = np.random.rand(*shape)
+    affine = np.eye(4)
+    img = nib.Nifti1Image(data, affine)
+    file_path = tmp_path / "synthetic_4d.nii.gz"
+    nib.save(img, file_path)
+    return str(file_path)
+
+@pytest.fixture
+def synthetic_tractogram(tmp_path):
+    """Generates a simple tractogram."""
+    from nibabel.streamlines.tractogram import Tractogram
+    from nibabel.streamlines.trk import TrkFile
+
+    streamlines = [
+        np.array([[0, 0, 0], [1, 1, 1], [2, 2, 2]], dtype=np.float32),
+        np.array([[10, 10, 10], [11, 10, 10], [12, 10, 10]], dtype=np.float32)
+    ]
+    tractogram = Tractogram(streamlines, affine_to_rasmm=np.eye(4))
+    file_path = tmp_path / "synthetic.trk"
+    TrkFile(tractogram).save(file_path)
+    return str(file_path)

tests/conftest.py

@@ -0,0 +1,41 @@
+import pytest
+from yabplot.data import get_available_resources, get_atlas_regions
+
+def test_get_available_resources():
+    """Verify that all resource categories exist and contain data."""
+    # all categories
+    res_all = get_available_resources(None)
+    assert isinstance(res_all, dict)
+
+    expected_categories = ['cortical', 'subcortical', 'tracts', 'bmesh']
+    for cat in expected_categories:
+        assert cat in res_all, f"expected category {cat} to be in resources"
+        assert len(res_all[cat]) > 0
+
+    # specific category
+    res_cortical = get_available_resources('cortical')
+    assert isinstance(res_cortical, list)
+    assert 'aparc' in res_cortical
+
+def test_get_atlas_regions_cortical():
+    """Verify that cortical atlas regions are correctly retrieved."""
+    regions = get_atlas_regions('aparc', 'cortical')
+    assert isinstance(regions, list)
+    assert len(regions) > 0
+
+def test_get_atlas_regions_subcortical():
+    """Verify that subcortical atlas regions are correctly retrieved."""
+    regions = get_atlas_regions('aseg', 'subcortical')
+    assert isinstance(regions, list)
+    assert len(regions) > 0
+
+def test_get_atlas_regions_tracts():
+    """Verify that tract atlas regions are correctly retrieved."""
+    regions = get_atlas_regions('xtract_tiny', 'tracts')
+    assert isinstance(regions, list)
+    assert len(regions) > 0
+
+def test_get_atlas_regions_invalid():
+    """Verify that invalid categories return an empty list gracefully."""
+    regions = get_atlas_regions('aparc', 'invalid_category')
+    assert regions == []