yabplot 0.4.0__tar.gz → 0.5.1__tar.gz

yabplot-0.5.1/CITATION.cff

@@ -0,0 +1,21 @@
+cff-version: 1.2.0
+message: "If you use yabplot in your research, please cite it as below."
+authors:
+- family-names: "Anijärv"
+  given-names: "Toomas Erik"
+  orcid: "https://orcid.org/0000-0002-3650-4230"
+title: "yabplot: yet another brain plot for unified neuroimaging visualization in Python"
+doi: 10.5281/zenodo.18237144
+version: 0.5.1
+url: "https://github.com/teanijarv/yabplot"
+preferred-citation:
+  type: software
+  authors:
+  - family-names: "Anijärv"
+    given-names: "Toomas Erik"
+    orcid: "https://orcid.org/0000-0002-3650-4230"
+  title: "yabplot: yet another brain plot for unified neuroimaging visualization in Python"
+  year: 2026
+  doi: 10.5281/zenodo.18237144
+  url: "https://github.com/teanijarv/yabplot"
+  abstract: "An open-source Python package for 3D neuroimaging visualization."

yabplot-0.5.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# code of conduct
+
+## our pledge
+in the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## our standards
+examples of behavior that contributes to creating a positive environment include:
+* using welcoming and inclusive language
+* being respectful of differing viewpoints and experiences
+* gracefully accepting constructive criticism
+* focusing on what is best for the community
+* showing empathy towards other community members
+
+examples of unacceptable behavior by participants include:
+* the use of sexualized language or imagery and unwelcome sexual attention or advances
+* trolling, insulting/derogatory comments, and personal or political attacks
+* public or private harassment
+* publishing others' private information, such as a physical or electronic address, without explicit permission
+* other conduct which could reasonably be considered inappropriate in a professional setting
+
+## our responsibilities
+as the maintainers of this project, we are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+we have the right and responsibility to remove, edit, or reject comments, commits, code, docs edits, issues, and other contributions that are not aligned to this code of conduct, or to ban temporarily or permanently any contributor for other behaviors that we deem inappropriate, threatening, offensive, or harmful.
+
+## enforcement
+instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting us at teanijarv@pm.me. all complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. we are obligated to maintain confidentiality with regard to the reporter of an incident.

yabplot-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# contributing to yabplot
+
+thank you for your interest in contributing to `yabplot`! we welcome contributions from the neuroimaging and open-source communities.
+
+## how to contribute
+
+### reporting bugs
+- use the [github issue tracker](https://github.com/teanijarv/yabplot/issues) to report bugs.
+- include a minimal reproducible example and information about your environment (os, python version, package versions).
+
+### suggesting enhancements
+- open an issue describing the proposed feature and why it would be useful for the community.
+
+### pull requests
+1. fork the repository and create your branch from `main`.
+2. if you've added code that should be tested, add tests in the `tests/` directory.
+3. if you've changed API, update the documentation.
+4. ensure the test suite passes: `uv run pytest tests/`
+5. submit a pull request with a clear description of the changes.
+
+## development setup
+
+we use `uv` for dependency management. to set up your development environment:
+
+```bash
+git clone https://github.com/teanijarv/yabplot.git
+cd yabplot
+uv venv
+uv pip install -e ".[docs]"
+uv pip install pytest
+```
+
+## community
+by contributing, you agree to abide by our [code of conduct](CODE_OF_CONDUCT.md).

yabplot-0.5.1/MANIFEST.in

@@ -0,0 +1,9 @@
+include pyproject.toml
+include README.md
+include LICENSE
+include CITATION.cff
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+
+recursive-include yabplot *.txt *.json *.md
+recursive-include tests *.py

{yabplot-0.4.0/yabplot.egg-info → yabplot-0.5.1}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: yabplot
-Version: 0.4.0
+Version: 0.5.1
 Summary: yet another brain plot
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cmocean>=4.0.3
 Requires-Dist: ipywidgets>=8.1.8
+Requires-Dist: matplotlib>=3.10.7
 Requires-Dist: nibabel>=5.3.2
 Requires-Dist: pandas>=2.3.3
 Requires-Dist: pooch>=1.8.2
@@ -31,17 +32,18 @@ Dynamic: license-file
 [![Tests](https://github.com/teanijarv/yabplot/actions/workflows/tests.yml/badge.svg)](https://github.com/teanijarv/yabplot/actions/workflows/tests.yml)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18237144.svg)](https://doi.org/10.5281/zenodo.18237144)
 
-**yabplot** is a Python library for creating beautiful, publication-quality 3D brain visualizations. it supports plotting cortical regions (+ vertexwise), subcortical structures, and white matter bundles.
+**yabplot** is a Python library for creating publication-quality 3D brain visualizations. it provides a unified interface for cortical regions, subcortical structures, white matter bundles, connectomes, voxel-wise maps, and vertex-wise maps.
 
-the idea is simple. while there are already amazing visualization tools available, they often focus on specific domains—using one tool for white matter tracts and another for cortical surfaces inevitably leads to inconsistent styles. i wanted a unified, simple-to-use tool that enables me (and hopefully others) to perform most brain visualizations in a single place. recognizing that neuroscience evolves daily, i designed **yabplot** to be modular: it supports standard pre-packaged atlases out of the box, but easily accepts any custom parcellation or tractography dataset you might need.
+the idea is simple. while there are already amazing visualization tools available, they often focus on specific domains—using one tool for white matter tracts and another for cortical surfaces inevitably leads to inconsistent styles. i wanted a unified, simple-to-use tool that enables me (and hopefully others) to perform most brain visualizations in a single place. recognizing that neuroscience evolves daily, i designed **yabplot** to be modular: it supports standard pre-packaged atlases out of the box, but easily accepts any custom parcellation or tractography dataset you might need. moreover, it enables to plot volumetric data either voxel-wise or by projecting the data to cortical surface or white matter tracts.
 
 ## features
 
-* **pre-existing atlases:** access many commonly used atlases (schaefer2018, brainnetome, aparc, aseg, musus100, xtract, etc) on demand.
-* **vertexwise plotting:** project volume (.nii) to cortical surface and plot.
-* **simple to use:** plug-n-play functions for cortex, subcortex, and tracts with a unified API.
-* **custom atlases:** easily use your own parcellations, segmentations (.nii/.gii), or tractograms (.trk).
-* **flexible inputs:** accepts data as dictionaries (for partial mapping) or arrays (for strict mapping).
+* **unified plotting API:** plot cortical regions, vertex-wise maps, subcortical structures, voxel-wise maps, white-matter tracts, and connectomes with a consistent interface.
+* **pre-packaged resources:** access commonly used atlases and meshes on demand, including schaefer, brainnetome, aparc, aseg, musus100, and xtract atlases.
+* **flexible data mapping:** pass data as arrays for strict ordering or dictionaries for partial/name-based mapping.
+* **custom atlases:** build and use custom cortical parcellations, subcortical segmentations, and tractography datasets.
+* **volume projection:** project nifti images to cortical surfaces or tractograms for vertex-wise and tractometry visualizations, or plot the volumes voxel-wise.
+* **publication-oriented output:** generate static figures, saved images, and interactive 3D views.
 
 ## installation
 
@@ -55,7 +57,7 @@ pip install yabplot # to install
 pip install yabplot --upgrade # to update
 ```
 
-dependencies: python 3.11 with ipywidgets, nibabel, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
+dependencies: python 3.11 with ipywidgets, nibabel, matplotlib, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
 
 (Connectome Workbench (`wb_command`) is a requirement to create custom cortical atlases unless you plan to only use pre-loaded atlases; see more in docs)
 
@@ -77,42 +79,53 @@ print(yab.get_available_resources())
 # see the region names for a specific atlas
 print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
 
-# cortical surface regions
+# plotting cortical surface regions
 atlas = 'aparc'
-dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
-yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh='midthickness', views=['left_lateral', 'left_medial'],
-                  figsize=(600, 300), cmap='viridis')
+dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086}
+ax = yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[0.0, 0.3], cmap='viridis',
+    bmesh='midthickness', views=['left_lateral', 'left_medial'])
 
-# subcortical structures
+# plotting subcortical regions
 atlas = 'aseg'
 regs = yab.get_atlas_regions(atlas=atlas, category='subcortical')
 data = np.arange(1, len(regs)+1)
-yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
-                     views=['left_lateral', 'superior', 'right_lateral'], 
-                     bmesh_alpha=0.1, figsize=(600, 300), cmap='viridis')
+ax = yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
+    views=['left_lateral', 'superior', 'right_lateral'], 
+    bmesh_alpha=0.1, cmap='plasma')
 
-# vertex-wise surface
+# plotting white matter tracts
+atlas = 'xtract_medium'
+regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
+data = {reg: np.sin(i) for i, reg in enumerate(regs)}
+ax = yab.plot_tracts(data=data, atlas=atlas, style='matte', cmap='coolwarm',
+    views=['left_lateral', 'anterior', 'superior'], bmesh='pial')
+
+# plotting connectome
+data = np.random.rand(400, 400)
+ax = yab.plot_connectome(matrix=data, atlas='schaefer400',
+    edge_cmap='dense', node_cmap='binary', edge_threshold='95%', 
+    views=['left_lateral', 'superior', 'posterior']
+)
+
+# volume projection to cortical surface and vertexwise plotting
 threshold = 4
 b_lh_path, b_rh_path = yab.data.get_surface_paths('midthickness', 'bmesh')
 lh_data, rh_data = yab.project_vol2surf('path/to/yourdata.nii.gz', bmesh='midthickness')
 lh_data = np.where(lh_data > threshold, lh_data, np.nan)
 rh_data = np.where(rh_data > threshold, rh_data, np.nan)
 lh_mesh, rh_mesh = yab.load_vertexwise_mesh(b_lh_path, b_rh_path, lh_data, rh_data)
-yab.plot_vertexwise(lh_mesh, rh_mesh, cmap='viridis', vminmax=[-4, 9], 
-                    views=['left_lateral', 'left_medial'], figsize=(600, 300))
+ax = yab.plot_vertexwise(lh_mesh, rh_mesh, cmap='viridis', vminmax=[-10, 10], 
+                    views=['left_lateral', 'left_medial'])
 
-# white matter bundles
-atlas = 'xtract_tiny'
-regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
-data = {reg: np.sin(i) for i, reg in enumerate(regs)}
-yab.plot_tracts(data=data, atlas=atlas, style='matte',
-                views=['left_lateral', 'anterior', 'superior'], bmesh='pial',
-                bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
+# plotting volume voxel-wise 
+threshold = '99.5%'
+nii_path = 'path/to/yourdata.nii.gz'
+ax = yab.plot_voxelwise(nii_path, threshold='99%', cmap='Reds',
+    views=['left_lateral', 'superior', 'anterior'])
 
 ```
 
-![examples](docs/assets/examples.png)
+![examples](docs/assets/overview.png)
 
 ## acknowledgements
 

{yabplot-0.4.0 → yabplot-0.5.1}/README.md

@@ -7,17 +7,18 @@
 [![Tests](https://github.com/teanijarv/yabplot/actions/workflows/tests.yml/badge.svg)](https://github.com/teanijarv/yabplot/actions/workflows/tests.yml)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18237144.svg)](https://doi.org/10.5281/zenodo.18237144)
 
-**yabplot** is a Python library for creating beautiful, publication-quality 3D brain visualizations. it supports plotting cortical regions (+ vertexwise), subcortical structures, and white matter bundles.
+**yabplot** is a Python library for creating publication-quality 3D brain visualizations. it provides a unified interface for cortical regions, subcortical structures, white matter bundles, connectomes, voxel-wise maps, and vertex-wise maps.
 
-the idea is simple. while there are already amazing visualization tools available, they often focus on specific domains—using one tool for white matter tracts and another for cortical surfaces inevitably leads to inconsistent styles. i wanted a unified, simple-to-use tool that enables me (and hopefully others) to perform most brain visualizations in a single place. recognizing that neuroscience evolves daily, i designed **yabplot** to be modular: it supports standard pre-packaged atlases out of the box, but easily accepts any custom parcellation or tractography dataset you might need.
+the idea is simple. while there are already amazing visualization tools available, they often focus on specific domains—using one tool for white matter tracts and another for cortical surfaces inevitably leads to inconsistent styles. i wanted a unified, simple-to-use tool that enables me (and hopefully others) to perform most brain visualizations in a single place. recognizing that neuroscience evolves daily, i designed **yabplot** to be modular: it supports standard pre-packaged atlases out of the box, but easily accepts any custom parcellation or tractography dataset you might need. moreover, it enables to plot volumetric data either voxel-wise or by projecting the data to cortical surface or white matter tracts.
 
 ## features
 
-* **pre-existing atlases:** access many commonly used atlases (schaefer2018, brainnetome, aparc, aseg, musus100, xtract, etc) on demand.
-* **vertexwise plotting:** project volume (.nii) to cortical surface and plot.
-* **simple to use:** plug-n-play functions for cortex, subcortex, and tracts with a unified API.
-* **custom atlases:** easily use your own parcellations, segmentations (.nii/.gii), or tractograms (.trk).
-* **flexible inputs:** accepts data as dictionaries (for partial mapping) or arrays (for strict mapping).
+* **unified plotting API:** plot cortical regions, vertex-wise maps, subcortical structures, voxel-wise maps, white-matter tracts, and connectomes with a consistent interface.
+* **pre-packaged resources:** access commonly used atlases and meshes on demand, including schaefer, brainnetome, aparc, aseg, musus100, and xtract atlases.
+* **flexible data mapping:** pass data as arrays for strict ordering or dictionaries for partial/name-based mapping.
+* **custom atlases:** build and use custom cortical parcellations, subcortical segmentations, and tractography datasets.
+* **volume projection:** project nifti images to cortical surfaces or tractograms for vertex-wise and tractometry visualizations, or plot the volumes voxel-wise.
+* **publication-oriented output:** generate static figures, saved images, and interactive 3D views.
 
 ## installation
 
@@ -31,7 +32,7 @@ pip install yabplot # to install
 pip install yabplot --upgrade # to update
 ```
 
-dependencies: python 3.11 with ipywidgets, nibabel, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
+dependencies: python 3.11 with ipywidgets, nibabel, matplotlib, pandas, pooch, pyvista, scikit-image, trame, trame-vtk, trame-vuetify
 
 (Connectome Workbench (`wb_command`) is a requirement to create custom cortical atlases unless you plan to only use pre-loaded atlases; see more in docs)
 
@@ -53,42 +54,53 @@ print(yab.get_available_resources())
 # see the region names for a specific atlas
 print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
 
-# cortical surface regions
+# plotting cortical surface regions
 atlas = 'aparc'
-dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
-yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh='midthickness', views=['left_lateral', 'left_medial'],
-                  figsize=(600, 300), cmap='viridis')
+dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086}
+ax = yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[0.0, 0.3], cmap='viridis',
+    bmesh='midthickness', views=['left_lateral', 'left_medial'])
 
-# subcortical structures
+# plotting subcortical regions
 atlas = 'aseg'
 regs = yab.get_atlas_regions(atlas=atlas, category='subcortical')
 data = np.arange(1, len(regs)+1)
-yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
-                     views=['left_lateral', 'superior', 'right_lateral'], 
-                     bmesh_alpha=0.1, figsize=(600, 300), cmap='viridis')
+ax = yab.plot_subcortical(data=data, atlas=atlas, vminmax=[2, 14], 
+    views=['left_lateral', 'superior', 'right_lateral'], 
+    bmesh_alpha=0.1, cmap='plasma')
 
-# vertex-wise surface
+# plotting white matter tracts
+atlas = 'xtract_medium'
+regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
+data = {reg: np.sin(i) for i, reg in enumerate(regs)}
+ax = yab.plot_tracts(data=data, atlas=atlas, style='matte', cmap='coolwarm',
+    views=['left_lateral', 'anterior', 'superior'], bmesh='pial')
+
+# plotting connectome
+data = np.random.rand(400, 400)
+ax = yab.plot_connectome(matrix=data, atlas='schaefer400',
+    edge_cmap='dense', node_cmap='binary', edge_threshold='95%', 
+    views=['left_lateral', 'superior', 'posterior']
+)
+
+# volume projection to cortical surface and vertexwise plotting
 threshold = 4
 b_lh_path, b_rh_path = yab.data.get_surface_paths('midthickness', 'bmesh')
 lh_data, rh_data = yab.project_vol2surf('path/to/yourdata.nii.gz', bmesh='midthickness')
 lh_data = np.where(lh_data > threshold, lh_data, np.nan)
 rh_data = np.where(rh_data > threshold, rh_data, np.nan)
 lh_mesh, rh_mesh = yab.load_vertexwise_mesh(b_lh_path, b_rh_path, lh_data, rh_data)
-yab.plot_vertexwise(lh_mesh, rh_mesh, cmap='viridis', vminmax=[-4, 9], 
-                    views=['left_lateral', 'left_medial'], figsize=(600, 300))
+ax = yab.plot_vertexwise(lh_mesh, rh_mesh, cmap='viridis', vminmax=[-10, 10], 
+                    views=['left_lateral', 'left_medial'])
 
-# white matter bundles
-atlas = 'xtract_tiny'
-regs = yab.get_atlas_regions(atlas=atlas, category='tracts')
-data = {reg: np.sin(i) for i, reg in enumerate(regs)}
-yab.plot_tracts(data=data, atlas=atlas, style='matte',
-                views=['left_lateral', 'anterior', 'superior'], bmesh='pial',
-                bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
+# plotting volume voxel-wise 
+threshold = '99.5%'
+nii_path = 'path/to/yourdata.nii.gz'
+ax = yab.plot_voxelwise(nii_path, threshold='99%', cmap='Reds',
+    views=['left_lateral', 'superior', 'anterior'])
 
 ```
 
-![examples](docs/assets/examples.png)
+![examples](docs/assets/overview.png)
 
 ## acknowledgements
 

{yabplot-0.4.0 → yabplot-0.5.1}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "yabplot"
-version = "0.4.0"
+version = "0.5.1"
 description = "yet another brain plot"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "cmocean>=4.0.3",
     "ipywidgets>=8.1.8",
+    "matplotlib>=3.10.7",
     "nibabel>=5.3.2",
     "pandas>=2.3.3",
     "pooch>=1.8.2",
@@ -31,3 +32,8 @@ include = ["yabplot*"]
 
 [tool.setuptools.package-data]
 "yabplot" = ["*.txt", "*.json"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]

yabplot-0.5.1/tests/conftest.py

@@ -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)

yabplot-0.5.1/tests/test_data.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 == []

yabplot-0.5.1/tests/test_mapping.py

@@ -0,0 +1,78 @@
+import pytest
+import numpy as np
+import pandas as pd
+from yabplot.mesh import map_values_to_surface
+from yabplot.utils import prep_data
+
+def test_prep_data_array():
+    """Verify that 1D arrays are correctly mapped to a dictionary by position."""
+    regions = ['A', 'B', 'C']
+    data = [1, 2, 3]
+    result = prep_data(data, regions, 'test_atlas', 'cortical')
+    assert isinstance(result, dict)
+    assert result['A'] == 1
+    assert result['C'] == 3
+
+def test_prep_data_dict():
+    """Verify that dictionaries are passed through correctly."""
+    regions = ['A', 'B', 'C']
+    data = {'A': 10, 'B': 20}
+    result = prep_data(data, regions, 'test_atlas', 'cortical')
+    assert isinstance(result, dict)
+    assert result['A'] == 10
+    assert result['B'] == 20
+
+def test_prep_data_series():
+    """Verify that pandas Series are correctly converted using their index."""
+    regions = ['A', 'B', 'C']
+    data = pd.Series([100, 200], index=['A', 'C'])
+    result = prep_data(data, regions, 'test_atlas', 'cortical')
+    assert result['A'] == 100
+    assert result['C'] == 200
+
+def test_prep_data_dataframe():
+    """Verify that pandas DataFrames are correctly handled by index or column mapping."""
+    regions = ['A', 'B', 'C']
+    # 1-col dataframe will use index as labels
+    data_1col = pd.DataFrame({'val': [5, 6]}, index=['B', 'A'])
+    result_1col = prep_data(data_1col, regions, 'test_atlas', 'cortical')
+    assert result_1col['A'] == 6
+    assert result_1col['B'] == 5
+
+    # 2-col dataframe will use first column as labels and second as values
+    df2 = pd.DataFrame({'Region': ['B', 'A'], 'Value': [50, 60]})
+    result_2col = prep_data(df2, regions, 'test_atlas', 'cortical')
+    assert result_2col['A'] == 60
+    assert result_2col['B'] == 50
+
+def test_prep_data_length_mismatch():
+    """Verify that an array length mismatch raises a ValueError."""
+    regions = ['A', 'B', 'C']
+    data = [1, 2] # length mismatch
+    with pytest.raises(ValueError, match="Data length mismatch"):
+        prep_data(data, regions, 'test_atlas', 'cortical')
+
+def test_map_values_to_surface():
+    """Verify that atlas scalar mapping correctly handles data injection and NaNs."""
+    target_labels = np.array([0, 1, 2, 1, 0, 3])
+    lut_ids = np.array([0, 1, 2, 3])
+    dense_lut_names = ['Region0', 'Region1', 'Region2', 'Region3']
+
+    # dict input
+    data_dict = {'Region1': 10.0, 'Region2': 20.0}
+    res_dict = map_values_to_surface(data_dict, target_labels, lut_ids, dense_lut_names)
+    assert np.isnan(res_dict[0]) # region 0 mapped to NaN
+    assert res_dict[1] == 10.0   # region 1 mapped to 10
+    assert res_dict[2] == 20.0   # region 2 mapped to 20
+    assert np.isnan(res_dict[5]) # target 3 -> region 3 mapped to NaN
+
+    # array input
+    data_arr = [0.0, 1.0, 2.0, 3.0]
+    res_arr = map_values_to_surface(data_arr, target_labels, lut_ids, dense_lut_names)
+    assert res_arr[0] == 0.0
+    assert res_arr[1] == 1.0
+    assert res_arr[5] == 3.0
+
+    # mismatch length array
+    with pytest.raises(ValueError):
+        map_values_to_surface([1.0, 2.0], target_labels, lut_ids, dense_lut_names)

yabplot-0.5.1/tests/test_mesh.py

@@ -0,0 +1,24 @@
+import pytest
+import numpy as np
+import pyvista as pv
+from yabplot.mesh import load_nii_as_mesh, make_cortical_mesh
+
+def test_load_nii_as_mesh(synthetic_nifti):
+    """Verify that marching cubes mesh extraction works on a NIfTI volume."""
+    mesh = load_nii_as_mesh(synthetic_nifti, threshold=5.0, blur_sigma=0, smooth_i=0)
+    assert isinstance(mesh, pv.PolyData)
+    assert mesh.n_points > 0
+    assert mesh.n_cells > 0
+
+def test_make_cortical_mesh():
+    """Verify that a manual mesh can be constructed from vertex and face arrays."""
+    verts = np.array([[0,0,0], [1,0,0], [0,1,0], [0,0,1]], dtype=np.float32)
+    faces = np.array([[0,1,2], [0,1,3], [0,2,3], [1,2,3]], dtype=np.int64)
+    scalars = np.array([1, 2, 3, 4], dtype=np.float32)
+    mesh = make_cortical_mesh(verts, faces, scalars, scalar_name='TestData')
+
+    assert isinstance(mesh, pv.PolyData)
+    assert mesh.n_points == 4
+    assert mesh.n_cells == 4
+    assert 'TestData' in mesh.point_data
+    assert np.all(mesh.point_data['TestData'] == scalars)

yabplot-0.5.1/tests/test_plotting.py

@@ -0,0 +1,93 @@
+import pytest
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import yabplot as yab
+import pyvista as pv
+
+# tell PyVista to run in "off-screen" mode so it doesn't try to open a real window
+pv.OFF_SCREEN = True
+
+def test_version():
+    """Check that the package has a version string."""
+    assert yab.__version__ is not None
+
+def test_none_returns_empty_dict():
+    """Verify that passing None disables the background mesh."""
+    result = yab.mesh.load_bmesh(None)
+    assert result == {}
+
+def test_dict_passthrough():
+    """Verify that custom dictionary keys for hemispheres are properly sanitized."""
+    mesh_l = pv.Sphere()
+    mesh_r = pv.Cube()
+    mesh_other = pv.Cone()
+    d = {'left': mesh_l, 'RIGHT': mesh_r, 'other': mesh_other}
+    result = yab.mesh.load_bmesh(d)
+    expected = {'L': mesh_l, 'R': mesh_r, 'other': mesh_other}
+    assert result == expected
+
+def test_polydata_wrapped_in_both():
+    """Verify that passing a single PyVista mesh safely wraps it."""
+    mesh = pv.Sphere()
+    result = yab.mesh.load_bmesh(mesh)
+    assert 'both' in result
+    assert result['both'] is mesh
+
+def test_plotter_instantiation():
+    """Smoke test: can we create a Plotter without crashing?"""
+    plotter = pv.Plotter(off_screen=True)
+    plotter.add_mesh(pv.Sphere())
+    plotter.show()
+    plotter.close()
+
+def test_plot_cortical():
+    """Smoke test: verify that plot_cortical renders with standard atlas."""
+    yab.plot_cortical(atlas='aparc', display_type='matplotlib')
+
+def test_plot_subcortical():
+    """Smoke test: verify that plot_subcortical renders with standard atlas."""
+    yab.plot_subcortical(atlas='aseg', display_type='matplotlib')
+
+def test_plot_tracts():
+    """Smoke test: verify that plot_tracts renders with standard atlas."""
+    yab.plot_tracts(atlas='xtract_tiny', display_type='matplotlib')
+
+def test_plot_vertexwise():
+    """Smoke test: verify that plot_vertexwise renders with custom meshes."""
+    lh = pv.Sphere()
+    rh = pv.Sphere()
+    lh['Data'] = np.random.rand(lh.n_points)
+    rh['Data'] = np.random.rand(rh.n_points)
+    yab.plot_vertexwise(lh, rh, display_type='matplotlib')
+
+def test_plot_voxelwise(synthetic_nifti):
+    """Smoke test: verify that plot_voxelwise renders with synthetic volume."""
+    yab.plot_voxelwise(synthetic_nifti, threshold=5.0, blur_sigma=0, display_type='matplotlib')
+
+def test_plot_connectome():
+    """Smoke test: verify that plot_connectome renders both nodes-only and matrix modes."""
+    yab.plot_connectome(atlas='aparc', display_type='matplotlib')
+    # plotting with a dummy matrix
+    regions = yab.get_atlas_regions('aparc', 'cortical')
+    n = len(regions)
+    matrix = np.random.rand(n, n)
+    yab.plot_connectome(matrix=matrix, atlas='aparc', edge_threshold=0.5, display_type='matplotlib')
+
+
+def test_matplotlib_ax_compatibility():
+    """Verify that plotting on a provided Matplotlib axis works correctly."""
+    fig, ax = plt.subplots()
+    ret_ax = yab.plot_cortical(atlas='aparc', ax=ax, display_type='matplotlib')
+    assert ret_ax is ax
+    # verify ax is usable
+    ret_ax.set_title("Test Title")
+    assert ret_ax.get_title() == "Test Title"
+    plt.close(fig)
+
+def test_export_path(tmp_path):
+    """Verify that export_path correctly saves a file to disk."""
+    out_file = tmp_path / "test_export.png"
+    yab.plot_cortical(atlas='aparc', display_type='matplotlib', export_path=str(out_file))
+    assert out_file.exists()
+    assert out_file.stat().st_size > 0