yabplot 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yabplot
-Version: 0.3.0
+Version: 0.4.0
 Summary: yet another brain plot
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -38,7 +38,7 @@ the idea is simple. while there are already amazing visualization tools availabl
 ## features
 
 * **pre-existing atlases:** access many commonly used atlases (schaefer2018, brainnetome, aparc, aseg, musus100, xtract, etc) on demand.
-* [new!] **vertexwise plotting:** project volume (.nii) to cortical surface and plot.
+* **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).
@@ -77,16 +77,12 @@ print(yab.get_available_resources())
 # see the region names for a specific atlas
 print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
 
-# cortical surfaces
+# cortical surface regions
 atlas = 'aparc'
 dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
-dmap2 = {'L_fusiform': 0.218, 'L_supramarginal': 0.119, ...}
 yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh_type='midthickness', views=['left_lateral', 'left_medial'],
-                  figsize=(600, 300), cmap='viridis', proc_vertices='sharp')
-yab.plot_cortical(data=dmap2, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh_type='swm', views=['left_lateral', 'left_medial'],
-                  figsize=(1200, 600), cmap='viridis', proc_vertices='sharp')
+                  bmesh='midthickness', views=['left_lateral', 'left_medial'],
+                  figsize=(600, 300), cmap='viridis')
 
 # subcortical structures
 atlas = 'aseg'
@@ -96,12 +92,22 @@ 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')
 
+# vertex-wise surface
+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))
+
 # 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_type='pial',
+                views=['left_lateral', 'anterior', 'superior'], bmesh='pial',
                 bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
 
 ```

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

@@ -14,7 +14,7 @@ the idea is simple. while there are already amazing visualization tools availabl
 ## features
 
 * **pre-existing atlases:** access many commonly used atlases (schaefer2018, brainnetome, aparc, aseg, musus100, xtract, etc) on demand.
-* [new!] **vertexwise plotting:** project volume (.nii) to cortical surface and plot.
+* **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).
@@ -53,16 +53,12 @@ print(yab.get_available_resources())
 # see the region names for a specific atlas
 print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
 
-# cortical surfaces
+# cortical surface regions
 atlas = 'aparc'
 dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
-dmap2 = {'L_fusiform': 0.218, 'L_supramarginal': 0.119, ...}
 yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh_type='midthickness', views=['left_lateral', 'left_medial'],
-                  figsize=(600, 300), cmap='viridis', proc_vertices='sharp')
-yab.plot_cortical(data=dmap2, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh_type='swm', views=['left_lateral', 'left_medial'],
-                  figsize=(1200, 600), cmap='viridis', proc_vertices='sharp')
+                  bmesh='midthickness', views=['left_lateral', 'left_medial'],
+                  figsize=(600, 300), cmap='viridis')
 
 # subcortical structures
 atlas = 'aseg'
@@ -72,12 +68,22 @@ 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')
 
+# vertex-wise surface
+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))
+
 # 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_type='pial',
+                views=['left_lateral', 'anterior', 'superior'], bmesh='pial',
                 bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
 
 ```

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

@@ -1,6 +1,6 @@
 [project]
 name = "yabplot"
-version = "0.3.0"
+version = "0.4.0"
 description = "yet another brain plot"
 readme = "README.md"
 requires-python = ">=3.10"

{yabplot-0.3.0 → yabplot-0.4.0}/tests/test_smoke.py

@@ -10,6 +10,37 @@ def test_version():
     """Check that the package has a version string."""
     assert yab.__version__ is not None
 
+def test_none_returns_empty_dict():
+    """
+    Unit test: Verify that passing None disables the background mesh 
+    by correctly returning an empty dictionary.
+    """
+    result = yab.mesh.load_bmesh(None)
+    assert result == {}
+
+def test_dict_passthrough():
+    """
+    Unit test: Verify that custom dictionary keys for hemispheres 
+    are properly sanitized to strict 'L' and 'R' keys.
+    """
+    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():
+    """
+    Unit test: Verify that passing a single PyVista mesh (whole brain) 
+    safely wraps it in a dictionary with the 'both' key.
+    """
+    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?
@@ -46,4 +77,4 @@ def test_plot_vertexwise():
     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=None)
+    yab.plot_vertexwise(lh, rh, display_type=None)

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/__init__.py

@@ -11,7 +11,10 @@ from .atlas_builder import (
     build_cortical_atlas, build_subcortical_atlas
 )
 from .mesh import (
-    load_vertexwise_mesh, project_vol2surf
+    load_vertexwise_mesh, make_cortical_mesh
+)
+from .projection import (
+    project_vol2surf, project_vol2tract, project_vol2tract_atlas
 )
 
 try:

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/atlas_builder.py

@@ -328,6 +328,12 @@ def build_subcortical_atlas(nii_path, labels_dict, out_dir, include_list=None, e
         # save as a vtk file
         out_file = os.path.join(out_dir, f"{name}.vtk")
         mesh.save(out_file)
+    
+    # file for ordering the labels
+    lut_path = os.path.join(out_dir, "atlas_LUT.txt")
+    with open(lut_path, 'w') as f:
+        for rid, name in targets.items():
+            f.write(f"{rid} {name}\n")
 
     print(f"\nsubcortical atlas successfully saved to: {out_dir}")
 

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/data/__init__.py

@@ -6,6 +6,7 @@ import os
 import glob
 from pathlib import Path
 import pooch
+import shutil
 
 from ..utils import parse_lut
 
@@ -165,8 +166,7 @@ def get_atlas_regions(atlas, category, custom_atlas_path=None):
     elif category == 'subcortical':
         try:
             file_map = _find_subcortical_files(atlas_dir)
-            # the plotting function sorts keys alphabetically
-            return sorted(list(file_map.keys()))
+            return _get_ordered_names(atlas_dir, file_map)
         except Exception as e:
             print(f"Error listing subcortical regions: {e}")
             return []
@@ -175,8 +175,7 @@ def get_atlas_regions(atlas, category, custom_atlas_path=None):
     elif category == 'tracts':
         try:
             file_map = _find_tract_files(atlas_dir)
-            # the plotting function sorts keys alphabetically
-            return sorted(list(file_map.keys()))
+            return _get_ordered_names(atlas_dir, file_map)
         except Exception as e:
             print(f"Error listing tracts: {e}")
             return []
@@ -188,26 +187,44 @@ def get_atlas_regions(atlas, category, custom_atlas_path=None):
 def _fetch_and_unpack(resource_key):
     """
     Downloads zip, unpacks it, deletes the zip to save space, 
-    and returns the extraction path.
+    and returns the extraction path. Forces a redownload if the 
+    registry hash changes (indicating an update).
     """
     extract_dir_name = resource_key.replace(".zip", "")
     extract_path = os.path.join(GOODBOY.path, extract_dir_name)
+    hash_file = os.path.join(extract_path, ".registry_hash")
 
-    # optimization: check if unpacked folder already exists
-    # if yes, skip pooch check entirely to avoid re-downloading
-    if os.path.isdir(extract_path) and os.listdir(extract_path):
-        return extract_path
+    # get the expected hash from the registry
+    expected_hash = GOODBOY.registry.get(resource_key)
+    if not expected_hash:
+        raise ValueError(f"Resource '{resource_key}' not found in registry.")
 
-    # fetch and unzip
+    # check if unpacked folder already exists and is up-to-date
+    is_up_to_date = False
+    if os.path.isdir(extract_path) and os.path.exists(hash_file):
+        with open(hash_file, 'r') as f:
+            local_hash = f.read().strip()
+        if local_hash == expected_hash:
+            is_up_to_date = True
+    if is_up_to_date:
+        return extract_path
+    # if folder exists but hash is wrong (outdated), wipe it clean
+    elif os.path.exists(extract_path):
+        print(f"Update found for '{extract_dir_name}'. Removing legacy data...")
+        shutil.rmtree(extract_path)
+        
+    # fetch and unzip new data
     try:
         GOODBOY.fetch(
             resource_key, 
             processor=pooch.Unzip(extract_dir=extract_dir_name)
         )
-    except ValueError:
-        # if key not in registry
-        available = list(GOODBOY.registry.keys())
-        raise ValueError(f"Resource '{resource_key}' not found in registry.")
+    except Exception as e:
+        raise RuntimeError(f"Failed to fetch '{resource_key}': {e}")
+    
+    # stamp the new folder with the updated hash
+    with open(hash_file, 'w') as f:
+        f.write(expected_hash)
 
     # cleanup: delete the source zip to save space
     zip_path = os.path.join(GOODBOY.path, resource_key)
@@ -225,7 +242,9 @@ def _resolve_resource_path(name, category, custom_path=None):
     if custom_path:
         if os.path.isdir(custom_path):
             return custom_path
-        raise FileNotFoundError(f"Custom atlas directory not found: {custom_path}")
+        if os.path.isfile(custom_path):
+            return custom_path
+        raise FileNotFoundError(f"Custom atlas directory/file not found: {custom_path}")
 
     # 2. standard download logic
     resource_key = f"{category}-{name}.zip"
@@ -326,6 +345,46 @@ def _find_cortical_files(atlas_dir, strict_name=None):
         
     return csv_path, lut_path
 
+def _get_ordered_names(atlas_dir, file_map):
+    """
+    Attempts to read the strict region order from a LUT or order text file.
+    Falls back to alphabetical sorting if no file exists.
+    """
+    txt_files = []
+
+    # look for a LUT or order file, ignoring qc reports
+    for root, dirs, files in os.walk(atlas_dir):
+        dirs[:] = [d for d in dirs if not d.startswith(('.', '__')) and 'qc_report' not in d]
+        for file in files:
+            if file.endswith('.txt') and 'registry' not in file:
+                txt_files.append(os.path.join(root, file))
+    def file_priority(filepath):
+        name = filepath.lower()
+        if 'lut' in name: return 0
+        if 'order' in name: return 1
+        return 2
+    txt_files.sort(key=file_priority)
+
+    if txt_files:
+        ordered_names = []
+        with open(txt_files[0], 'r') as f:
+            for line in f:
+                parts = line.strip().split()
+                # assuming standard LUT format (ID Name ...) or simple list (ID Name)
+                if len(parts) >= 2:
+                    name = parts[1]
+                    if name in file_map and name not in ordered_names:
+                        ordered_names.append(name)
+        
+        # append any stray files that exist in the directory but weren't in the text file
+        for name in sorted(file_map.keys()):
+            if name not in ordered_names:
+                ordered_names.append(name)
+        
+        return ordered_names
+
+    # legacy fallback: alphabetical
+    return sorted(list(file_map.keys()))
 
 def _find_subcortical_files(atlas_dir):
     """
@@ -403,8 +462,15 @@ def _find_tract_files(atlas_dir):
             
         return candidates
 
-    # scan for both .trk and .tck
-    found_files = _scan_for_ext(atlas_dir, ".trk") + _scan_for_ext(atlas_dir, ".tck")
+    if  os.path.isdir(atlas_dir):
+        # scan for both .trk and .tck
+        found_files = _scan_for_ext(atlas_dir, ".trk") + _scan_for_ext(atlas_dir, ".tck")
+    elif os.path.isfile(atlas_dir):
+        if atlas_dir.endswith((".trk", ".tck")):
+            found_files = [atlas_dir]
+    else:
+        raise ValueError(f"Invalid atlas directory/file path: {atlas_dir}, no valid tck or trk file found.")
+
     
     if not found_files:
         raise FileNotFoundError(f"No .trk or .tck files found in {atlas_dir}")

yabplot-0.4.0/yabplot/data/registry.txt

@@ -0,0 +1,30 @@
+cortical-aparc.zip sha256:9e3e4853c580b6ed7c70a2b398b8ddacfc30e05600f04f722d3b5e8ee28ba119 https://osf.io/q5a2v/download
+cortical-aal3.zip sha256:da90797ab768cb9b0ad1acf1a9035d62debdb823d0bcc2b96405b7e86c75a7dc https://osf.io/rcjqk/download
+cortical-brainnetome.zip sha256:42b828d5dd5734a34fb61282b1ee92c1961c4c3e3cc35fa73d3f48f6c12c0fcd https://osf.io/5nr4x/download
+cortical-schaefer100.zip sha256:79358c491ee2d9400e8166552a7e4d3f8ad7332e65192f0edf215d657f317896 https://osf.io/782gu/download
+cortical-schaefer200.zip sha256:e24ab0fe4acec59604ce2a98ef9f4c14cc3c3d6dea73fb31c6900bd3879ea138 https://osf.io/9uzc8/download
+cortical-schaefer300.zip sha256:ef096c2b96b0a8e1998417c23162f0e69f0693852911e55cb03f9681cc398669 https://osf.io/jcu8a/download
+cortical-schaefer400.zip sha256:000c1a3b71926d83ea8c73fed63c8688d34c3cd8f0b8f91bd5c7f4c80edf7554 https://osf.io/k8dvw/download
+cortical-schaefer1000.zip sha256:369827006e724e5ac74ef6a3761e2f77b5b30f2825e09d9a02c169dc5d3fbe90 https://osf.io/m3ze7/download
+subcortical-aal3.zip sha256:7d0965016a393e20f86bb4b20761854e5fc74731a83aff51e56eddec9f2d6f21 https://osf.io/yvheg/download
+subcortical-aal3_nocer.zip sha256:742e88052056dae851916dfaaac87173eeda5e74ec17bd44639140a34d70be04 https://osf.io/a59sj/download
+subcortical-aseg.zip sha256:083ba39d80bd42e92344ac5bb46cf520e60ddb31a4cce6f5bcb9dc54892d4e27 https://osf.io/8akre/download
+subcortical-brainnetome_sc.zip sha256:e008a3310bd8b80477af3685097800aa923487519274214eb2e0488109730051 https://osf.io/f9u3m/download
+subcortical-musus100.zip sha256:61ed78eafc9f407e625a0288c0ed2cf9273b833a5341e9712d30a26974976140 https://osf.io/ak3hb/download
+subcortical-musus100_dbn.zip sha256:8c79864c0cf37b2bc23752931742061be8a583a9064974bd52368ca657320555 https://osf.io/9g5z7/download
+subcortical-musus100_tha.zip sha256:14f44f5b7b7ac24eb3870600f87fa66b862d3b5a7403039b3b9c219f2bf28cdf https://osf.io/xrd9j/download
+subcortical-tian2020_s1.zip sha256:90c5c78a3d4636aea94944d54b24a3c0510580f6ca62fdb9192a316fd8e1a9cf https://osf.io/9z7wm/download
+tracts-hcp1065_medium.zip sha256:366bb100074cf7b1e55586e5468653f0c342e42cfdd91dca6d99b6fde82f06ff https://osf.io/kjf8e/download
+tracts-hcp1065_small.zip sha256:020f23059c3a20ee0dda8ad12cd3df99b9fe5d3b37e7a6b9ae34b8a52b4b4346 https://osf.io/ynpa5/download
+tracts-hcp1065_tiny.zip sha256:54380d82f5cd234029c6fc011910e00f0ad859fdb6c22c6aaa6452d055449ae9 https://osf.io/jzk7p/download
+tracts-xtract_large.zip sha256:e2d59e9f90b024018788af87e389f93b2fa9ac213604601966a44d7f81c9d89f https://osf.io/pktq6/download
+tracts-xtract_medium.zip sha256:f095028d3dfc0f974ebef1feffe4006b5bac1366325a784ea2301c56f583b1e7 https://osf.io/7tbjg/download
+tracts-xtract_small.zip sha256:9d3fe2c57acb87e8d13eb40a49a6c2c354dbe1a020122b693e9bf713e57cad5b https://osf.io/bmn3a/download
+tracts-xtract_tiny.zip sha256:469f9ed8ed5ceb7f8e17c9a0a92f1491d540814f832ef56441a7539532111f41 https://osf.io/a73x2/download
+bmesh-inflated.zip sha256:ba72f9e75f16fe767f6bbcec5c98381f6a20b2f5e2092505b4692844a1686461 https://osf.io/kfzjg/download
+bmesh-midthickness.zip sha256:ef8209853e1dac8804a60b5cde0b653ef2f6c77b6c7536f7acaa69a46dbb06c0 https://osf.io/xaktf/download
+bmesh-pial.zip sha256:5e36ba7883dd2a88485fc45c9166ed48e22db607d45655242961242b51f9f126 https://osf.io/knpg8/download
+bmesh-swm.zip sha256:1a516c070cb63557751d841d5cf75772660872b89ec749ee19c23298d77fa807 https://osf.io/hpbc9/download
+bmesh-very_inflated.zip sha256:8c33a00c718a47f0af118ce2c5804a2adf13d79be05c4665ca26582e3e8dd977 https://osf.io/xp9jr/download
+bmesh-white.zip sha256:b885ac1a4dcdf9e241a97e8d3ca59d7b1c86d8a3ebe17df512993bc5c1c0354a https://osf.io/wfc5t/download
+label-nomedialwall.zip sha256:03bd589b151814a1fc5e48236a78decf1a51791f04c3f4a521d2ed4fb214317b https://osf.io/2rgmc/download

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/mesh.py

@@ -1,14 +1,53 @@
-import os
-import warnings
-
 import numpy as np
-import nibabel as nib
 import pyvista as pv
-
 import scipy.sparse as sp
-from scipy.ndimage import map_coordinates
 
-from .utils import load_gii
+def load_bmesh(bmesh):
+    """
+    Transforms the `bmesh` parameter into a standardized dictionary of PyVista PolyData meshes.
+
+    Parameters
+    ----------
+    bmesh : None, str, dict, or pyvista.PolyData
+        - None: Returns an empty dictionary (disables background mesh).
+        - str: Fetches standard meshes from the registry (e.g., 'midthickness').
+        - dict: Maps custom meshes to 'L' and 'R' keys. Values can be pre-loaded 
+          PyVista PolyData objects or string file paths (which are auto-loaded).
+        - pyvista.PolyData: A single unified mesh, mapped to the 'both' key.
+
+    Returns
+    -------
+    dict
+        Standardized dictionary containing the loaded PyVista meshes.
+    """
+    from .data import get_surface_paths
+    from .utils import load_gii2pv
+
+    if bmesh is None:
+        return {}
+    if isinstance(bmesh, str):
+        lh_path, rh_path = get_surface_paths(bmesh, 'bmesh')
+        return {'L': load_gii2pv(lh_path), 'R': load_gii2pv(rh_path)}
+    if isinstance(bmesh, dict):
+        clean_dict = {}
+        for k, v in bmesh.items():
+            if isinstance(v, str):
+                if v.endswith('.gii') or v.endswith('.gii.gz'):
+                    v = load_gii2pv(v)
+                else:
+                    v = pv.read(v)
+            if k.upper() in ['L', 'LEFT']: clean_dict['L'] = v
+            elif k.upper() in ['R', 'RIGHT']: clean_dict['R'] = v
+            else: clean_dict[k] = v
+        return clean_dict
+    
+    return {'both': bmesh}
+
+def extract_polydata(mesh_hemi: pv.PolyData):
+    """Return vertices and rotated faces for plotting."""
+    v = mesh_hemi.points
+    f = mesh_hemi.faces.reshape(-1, 4)[:, 1:]
+    return v, f
     
 def make_cortical_mesh(verts, faces, scalars, scalar_name='Data'):
     """
@@ -60,6 +99,7 @@ def load_vertexwise_mesh(lh_mesh_path, rh_mesh_path, lh_data, rh_data, scalar_na
     lh_mesh, rh_mesh : tuple of pyvista.PolyData
         left and right hemisphere meshes ready for `yabplot.plotting.plot_vertexwise`.
     """
+    from .utils import load_gii
     lh = make_cortical_mesh(*load_gii(lh_mesh_path), lh_data, scalar_name)
     rh = make_cortical_mesh(*load_gii(rh_mesh_path), rh_data, scalar_name)
     return lh, rh
@@ -222,89 +262,3 @@ def lines_from_streamlines(streamlines):
         tangents.append(vecs / norms)
         
     return points, lines, np.vstack(tangents)
-
-
-def project_vol2surf(nii_path, bmesh_type='midthickness', custom_bmesh_paths=None, 
-                     mask_medial_wall=True, interpolation='linear'):
-    """
-    Projects a 3D NIfTI volume onto 2D cortical surface vertices.
-
-    It maps volumetric data directly onto surface meshes by converting real-world coordinates 
-    using the image affine and sampling the data array at those exact points.
-
-    Parameters
-    ----------
-    nii_path : str
-        absolute path to the 3D or 4D NIfTI volume. 
-        if 4D, only the first volume/timepoint is used.
-    bmesh_type : str, optional
-        name of the standard background mesh to use for projection coordinates. 
-        default is 'midthickness'.
-    custom_bmesh_paths : tuple of str, optional
-        custom paths for (lh_mesh, rh_mesh) if not using standard yabplot meshes.
-        default is None.
-    mask_medial_wall : bool, optional
-        whether to automatically set the medial wall vertices to NaN to prevent 
-        subcortical signal from bleeding onto the cortical surface. 
-        default is True.
-    interpolation : {'linear', 'nearest'}, optional
-        interpolation method for sampling the volume. 'linear' performs trilinear 
-        interpolation (smoother, good for continuous t-stats), while 'nearest' 
-        snaps to the closest voxel center (strictly required for p-values or atlases). 
-        default is 'linear'.
-
-    Returns
-    -------
-    lh_data : numpy.ndarray
-        1D array of projected values for the left hemisphere vertices.
-    rh_data : numpy.ndarray
-        1D array of projected values for the right hemisphere vertices.
-    """
-    from .data import get_surface_paths
-
-    # load volume
-    img = nib.load(nii_path)
-    vol_data = img.get_fdata()
-    
-    # check for 4d data (e.g. raw fmri timeseries)
-    if vol_data.ndim > 3:
-        warnings.warn(f"[WARNING] detected {vol_data.ndim}d nifti volume. using the first volume (index 0).")
-        vol_data = vol_data[..., 0] 
-        
-    # invert affine to go from real-world mm space back to voxel indices
-    inv_affine = np.linalg.inv(img.affine)
-
-    # resolve surfaces
-    if custom_bmesh_paths:
-        lh_path, rh_path = custom_bmesh_paths
-    else:
-        lh_path, rh_path = get_surface_paths(bmesh_type, 'bmesh')
-        
-    lh_v, _ = load_gii(lh_path)
-    rh_v, _ = load_gii(rh_path)
-
-    def sample_surface(vertices, volume, inv_aff, interp):
-        # convert [x, y, z] to [x, y, z, 1] to allow 4x4 affine matrix multiplication
-        coords_homo = np.hstack((vertices, np.ones((vertices.shape[0], 1))))
-        
-        # multiply by inverse affine to get exact decimal voxel coordinates
-        vox_coords = inv_aff.dot(coords_homo.T)[:3, :]
-        
-        # set scipy interpolation order (1 = trilinear, 0 = nearest neighbor)
-        order = 1 if interp == 'linear' else 0
-        
-        # sample the 3d volume at the calculated decimal coordinates
-        sampled_data = map_coordinates(volume, vox_coords, order=order, mode='nearest')
-        return sampled_data
-
-    # projection
-    lh_data = sample_surface(lh_v, vol_data, inv_affine, interpolation)
-    rh_data = sample_surface(rh_v, vol_data, inv_affine, interpolation)
-
-    # mask out the medial wall (optional but default true)
-    if mask_medial_wall:
-        lh_mask_path, rh_mask_path = get_surface_paths('nomedialwall', 'label')
-        lh_data[nib.load(lh_mask_path).darrays[0].data == 0] = np.nan
-        rh_data[nib.load(rh_mask_path).darrays[0].data == 0] = np.nan
-
-    return lh_data, rh_data

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/plotting.py

@@ -8,18 +8,18 @@ from matplotlib.colors import ListedColormap
 
 from .data import (
     get_surface_paths, _resolve_resource_path, _find_cortical_files, 
-    _find_subcortical_files, _find_tract_files
+    _find_subcortical_files, _find_tract_files, get_atlas_regions
 )
 
 from .utils import (
-    load_gii, load_gii2pv, prep_data, 
+    load_gii, load_gii2pv, prep_data,
     generate_distinct_colors, parse_lut
 )
 
 from .mesh import (
     map_values_to_surface, get_puzzle_pieces, apply_internal_blur, 
     apply_dilation, get_smooth_mask, lines_from_streamlines, 
-    make_cortical_mesh
+    make_cortical_mesh, load_bmesh, extract_polydata
 )
 
 from .scene import (
@@ -28,7 +28,6 @@ from .scene import (
 )
 
 
-
 def _render_cortical_views(lh_v, lh_f, lh_vals, rh_v, rh_f, rh_vals, is_cat,
                            views, layout, figsize, cmap, vminmax, nan_color, 
                            style, zoom, proc_vertices, display_type, export_path,
@@ -114,7 +113,7 @@ def _render_cortical_views(lh_v, lh_f, lh_vals, rh_v, rh_f, rh_vals, is_cat,
 ### PLOT FOR ATLAS-BASED CORTICAL DATA ###
 
 def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, layout=None, 
-                  bmesh_type='midthickness', figsize=(1000, 600), cmap='coolwarm', vminmax=[None, None], 
+                  bmesh='midthickness', figsize=(1000, 600), cmap='coolwarm', vminmax=[None, None], 
                   nan_color=(1.0, 1.0, 1.0), style='default', zoom=1.2, proc_vertices=None,
                   display_type='static', export_path=None):
     """
@@ -142,7 +141,7 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
         or a dictionary of camera configurations. Defaults to all views.
     layout : tuple (rows, cols), optional
         Grid layout for subplots. If None, automatically calculated based on the number of views.
-    bmesh_type : str
+    bmesh : str
         Name of the background context brain mesh (e.g., 'midthickness', 'white', 'swm', etc). 
         Default is 'midthickness'.
     figsize : tuple (width, height), optional
@@ -182,7 +181,7 @@ def plot_cortical(data=None, atlas=None, custom_atlas_path=None, views=None, lay
     is_cat = (data is None)
 
     # load brain mesh
-    b_lh_path, b_rh_path = get_surface_paths(bmesh_type, 'bmesh')
+    b_lh_path, b_rh_path = get_surface_paths(bmesh, 'bmesh')
     lh_v, lh_f = load_gii(b_lh_path)
     rh_v, rh_f = load_gii(b_rh_path)
 
@@ -219,8 +218,8 @@ def plot_vertexwise(lh, rh, scalars='Data', views=None, layout=None, figsize=(10
     Visualize arbitrary per-vertex scalar data on a user-supplied brain mesh.
 
     Unlike `plot_cortical`, this function requires no atlas. The user provides 
-    PyVista PolyData meshes (e.g., from `make_cortical_mesh`) with per-vertex 
-    scalar data stored under the key specified by `scalars`.
+    PyVista PolyData meshes with per-vertex scalar data stored under the key specified 
+    by `scalars`.
 
     Parameters
     ----------
@@ -281,11 +280,9 @@ def plot_vertexwise(lh, rh, scalars='Data', views=None, layout=None, figsize=(10
     """
 
     # extract v, f, raw from PyVista meshes
-    lh_v = lh.points
-    lh_f = lh.faces.reshape(-1, 4)[:, 1:]
+    lh_v, lh_f = extract_polydata(lh)
     lh_vals_raw = lh[scalars]
-    rh_v = rh.points
-    rh_f = rh.faces.reshape(-1, 4)[:, 1:]
+    rh_v, rh_f = extract_polydata(rh)
     rh_vals_raw = rh[scalars]
 
     # render
@@ -301,7 +298,7 @@ def plot_vertexwise(lh, rh, scalars='Data', views=None, layout=None, figsize=(10
 
 def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None, layout=None, 
                      figsize=(1000, 600), cmap='coolwarm', vminmax=[None, None], nan_color='#cccccc', 
-                     nan_alpha=1.0, style='default', bmesh_type='midthickness', 
+                     nan_alpha=1.0, style='default', bmesh='midthickness',
                      bmesh_alpha=0.1, bmesh_color='lightgray', zoom=1.2, display_type='static', 
                      export_path=None, custom_atlas_proc=dict(smooth_i=15, smooth_f=0.6)):
     """
@@ -339,10 +336,11 @@ def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None,
     nan_alpha : float, optional
         Opacity (0.0 to 1.0) for regions with no data. Set to 0.0 to hide them.
     style : str, optional
-        Lighting preset ('default', 'matte', 'glossy', 'sculpted', 'flat').
-    bmesh_type : str or None, optional
-        Name of the background context brain mesh (e.g., 'midthickness', 'white', 'swm', etc). 
-        Set to None to hide the context brain. Default is 'midthickness'.
+        Lighting preset ('default', 'matte', 'glossy', 'sculpted', 'flat').      
+    bmesh : pyvista.PolyData or dict, optional                                                                                                   
+        Configure background context brain mesh. Accepts a string 
+        (e.g., 'midthickness', 'white', 'swm', etc), single PolyData (used for both hemispheres)                                                        
+        or a dict with 'L'/'R' keys. Default is 'midthickness'.
     bmesh_alpha : float, optional
         Opacity of the context brain mesh. Default is 0.1.
     bmesh_color : str, optional
@@ -370,21 +368,16 @@ def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None,
     if atlas is None and custom_atlas_path is None:
         atlas = 'aseg'
 
-    # load context brain mesh (if requested)
-    bmesh = {}
-    if bmesh_type:
-        b_lh_path, b_rh_path = get_surface_paths(bmesh_type, 'bmesh')
-        bmesh['L'] = load_gii2pv(b_lh_path)
-        bmesh['R'] = load_gii2pv(b_rh_path)
+    # load context brain mesh (if requested) or accept mesh directly
+    ctx_meshes = load_bmesh(bmesh)
     
     # load regional atlas meshes
-
     # resolve atlas path (either download or custom directory)
     atlas_dir = _resolve_resource_path(atlas, 'subcortical', custom_path=custom_atlas_path)
 
     # locate mesh files, returns dict: {'Left_Thalamus': '/path/to/Left_Thalamus.vtk', ...}
     file_map = _find_subcortical_files(atlas_dir)
-    rmesh_names = sorted(list(file_map.keys()))
+    rmesh_names = get_atlas_regions(atlas, 'subcortical', custom_atlas_path)
 
     # load meshes (and convert gii2pv if gii files)
     meshes = {}
@@ -422,7 +415,7 @@ def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None,
         plotter.subplot(i // ncols, i % ncols)
 
         # add context (uses style kwargs for consistent lighting)
-        add_context_to_view(plotter, bmesh, cfg['side'], bmesh_alpha, bmesh_color, 
+        add_context_to_view(plotter, ctx_meshes, cfg['side'], bmesh_alpha, bmesh_color, 
                             **shading_params)
 
         # add regions
@@ -430,8 +423,8 @@ def plot_subcortical(data=None, atlas=None, custom_atlas_path=None, views=None,
             # side filter
             # TODO: make the hemisphere specific name check more robust
             name_lower = name.lower()
-            is_left = any(x in name_lower for x in ['left']) or name_lower.startswith('l-') or name_lower.endswith('_l')
-            is_right = any(x in name_lower for x in ['right']) or name_lower.startswith('r-') or name_lower.endswith('_r')
+            is_left = any(x in name_lower for x in ['left']) or name_lower.startswith('l-') or name_lower.endswith('_l') or name_lower.endswith('-lh')
+            is_right = any(x in name_lower for x in ['right']) or name_lower.startswith('r-') or name_lower.endswith('_r') or name_lower.endswith('-rh')
             
             if cfg['side'] == 'L' and is_right and not is_left: continue
             if cfg['side'] == 'R' and is_left and not is_right: continue
@@ -483,7 +476,7 @@ def clear_tract_cache():
 def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layout=None, 
                 figsize=(1000, 800), cmap='coolwarm', alpha=1.0, vminmax=[None, None], 
                 nan_color='#BDBDBD', nan_alpha=1.0, style='default',
-                bmesh_type='midthickness', bmesh_alpha=0.2, bmesh_color='lightgray', 
+                bmesh='midthickness', bmesh_alpha=0.2, bmesh_color='lightgray', 
                 zoom=1.2, orientation_coloring=False, display_type='static', 
                 tract_kwargs=dict(render_lines_as_tubes=True, line_width=1.2),
                 export_path=None):
@@ -496,7 +489,7 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
     Parameters
     ----------
     data : dict, list, numpy.ndarray, pandas.Series, pandas.DataFrame, optional
-        Scalar values for each tract.
+        Scalar values for each tract, or mrtrix3 derived .tsf file path for each tract.
         If dict: Keys must match tract names.
         If array/list: Must strictly match the sorted list of tracts in the atlas.
         If None: Tracts are colored by category (distinct colors) or orientation.
@@ -526,9 +519,10 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
         Opacity (0.0 to 1.0) for regions with no data. Set to 0.0 to hide them.
     style : str, optional
         Lighting preset ('default', 'matte', 'glossy', 'sculpted', 'flat').
-    bmesh_type : str or None, optional
-        Name of the background context brain mesh (e.g., 'midthickness', 'white', 'swm', etc). 
-        Set to None to hide the context brain. Default is 'midthickness'.
+    bmesh : pyvista.PolyData or dict, optional                                                                                                   
+        Configure background context brain mesh. Accepts a string 
+        (e.g., 'midthickness', 'white', 'swm', etc), single PolyData (used for both hemispheres)                                                        
+        or a dict with 'L'/'R' keys. Default is 'midthickness'.
     bmesh_alpha : float, optional
         Opacity of the context brain mesh. Default is 0.2.
     bmesh_color : str, optional
@@ -563,14 +557,22 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
 
     # locate tract files, returns dict eg {'CST_L': '/path/to/CST_L.trk', ...}
     file_map = _find_tract_files(atlas_dir)
-    tract_names = sorted(list(file_map.keys()))
+    tract_names = get_atlas_regions(atlas, 'tracts', custom_atlas_path)
 
     # prepare colors and map data
     if data is not None:
         d_data = prep_data(data, tract_names, atlas, 'tracts')
-        valid_vals = [v for v in d_data.values() if pd.notna(v)]
-        vmin = vminmax[0] if vminmax[0] is not None else (min(valid_vals) if valid_vals else 0)
-        vmax = vminmax[1] if vminmax[1] is not None else (max(valid_vals) if valid_vals else 1)
+        all_vals = []
+        for v in d_data.values():
+            v_arr = np.atleast_1d(v)
+            all_vals.append(v_arr[~np.isnan(v_arr)])
+            
+        if all_vals:
+            valid_vals = np.concatenate(all_vals)
+            vmin = vminmax[0] if vminmax[0] is not None else (np.min(valid_vals) if len(valid_vals) else 0)
+            vmax = vminmax[1] if vminmax[1] is not None else (np.max(valid_vals) if len(valid_vals) else 1)
+        else:
+            vmin, vmax = 0, 1
         c_vlim = [vmin, vmax]
     # categorical/orientation mode
     else:
@@ -579,11 +581,7 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
         c_vlim = [0, 1]
 
     # load context brain mesh (if requested)
-    bmesh = {}
-    if bmesh_type:
-        b_lh_path, b_rh_path = get_surface_paths(bmesh_type, 'bmesh')
-        bmesh['L'] = load_gii2pv(b_lh_path)
-        bmesh['R'] = load_gii2pv(b_rh_path)
+    ctx_meshes = load_bmesh(bmesh)
 
     # setup plotter
     sel_views = get_view_configs(views)
@@ -632,7 +630,7 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
         plotter.subplot(i // ncols, i % ncols)
         
         # add context (passed shading params to context mesh)
-        add_context_to_view(plotter, bmesh, cfg['side'], bmesh_alpha, bmesh_color, **shading_params)
+        add_context_to_view(plotter, ctx_meshes, cfg['side'], bmesh_alpha, bmesh_color, **shading_params)
 
         # add tracts
         for name in tract_names:
@@ -641,16 +639,25 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
             val = np.nan
             
             if data is not None and not orientation_coloring:
-                if name in d_data and pd.notna(d_data[name]):
+                # check data
+                if name in d_data and d_data[name] is not None:
                     val = d_data[name]
-                    has_value = True
-                elif nan_alpha == 0:
-                    continue 
+                    if np.isscalar(val) and np.isnan(val):
+                        has_value = False
+                    elif not np.isscalar(val) and np.all(np.isnan(val)):
+                        has_value = False
+                    else:
+                        has_value = True
+                else:
+                    has_value = False
+
+                if not has_value and nan_alpha == 0:
+                    continue
             
             # side filtering
             name_lower = name.lower()
-            is_left = any(x in name_lower for x in ['left', '_l', '-l', 'l_']) or name_lower.endswith('l')
-            is_right = any(x in name_lower for x in ['right', '_r', '-r', 'r_']) or name_lower.endswith('r')
+            is_left = any(x in name_lower for x in ['left', '_l', '-l', 'l_'])# or name_lower.endswith('l')
+            is_right = any(x in name_lower for x in ['right', '_r', '-r', 'r_'])# or name_lower.endswith('r')
             if cfg['side'] == 'L' and is_right and not is_left: continue
             if cfg['side'] == 'R' and is_left and not is_right: continue
 
@@ -661,16 +668,29 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
 
             # start with style presets, then override with tract_kwargs and dynamic props
             props = shading_params.copy()
-            props.update(tract_kwargs) 
-            
+            props.update(tract_kwargs)
+
             if orientation_coloring:
                 pv_mesh['Data'] = pv_mesh.point_data['tangents']
+
                 props.update({
                     'scalars': 'Data', 'rgb': True, 'opacity': alpha
                 })
 
             elif data is not None:
-                pv_mesh['Data'] = np.full(pv_mesh.n_points, val)
+                if np.isscalar(val):
+                    pv_mesh['Data'] = np.full(pv_mesh.n_points, val)
+                elif len(val) == 1:
+                    pv_mesh['Data'] = np.full(pv_mesh.n_points, val[0])
+                elif len(val) == pv_mesh.n_points:
+                    pv_mesh['Data'] = val
+                else:
+                    raise ValueError(
+                        f"Data shape mismatch for tract '{name}'. Must be a scalar "
+                        f"or a 1D array matching the number of points. "
+                        f"Array shape: {np.shape(val)}, mesh points: {pv_mesh.n_points}"
+                    )
+
                 current_opacity = alpha if has_value else nan_alpha
                 
                 props.update({
@@ -703,4 +723,4 @@ def plot_tracts(data=None, atlas=None, custom_atlas_path=None, views=None, layou
         del plotter
         gc.collect()
 
-    return ret_val
+    return ret_val

yabplot-0.4.0/yabplot/projection.py

@@ -0,0 +1,169 @@
+import warnings
+import numpy as np
+import nibabel as nib
+from scipy.ndimage import map_coordinates
+
+def project_vol2surf(nii_path, bmesh='midthickness', mask_medial_wall=True, interpolation='linear'):
+    """
+    Projects a 3D NIfTI volume onto 2D cortical surface vertices.
+
+    It maps volumetric data directly onto surface meshes by converting real-world coordinates 
+    using the image affine and sampling the data array at those exact points.
+
+    Parameters
+    ----------
+    nii_path : str
+        absolute path to the 3D or 4D NIfTI volume. 
+        if 4D, only the first volume/timepoint is used.
+    bmesh : str, dict, or pyvista.PolyData, optional
+        background mesh to use for projection coordinates. accepts a standard 
+        string (e.g., 'midthickness') or a dictionary of custom pyvista meshes 
+        {'L': mesh, 'R': mesh}. default is 'midthickness'.
+    mask_medial_wall : bool, optional
+        whether to automatically set the medial wall vertices to NaN to prevent 
+        subcortical signal from bleeding onto the cortical surface. 
+        Note: only supported if `bmesh` is a standard string. default is True.
+    interpolation : {'linear', 'nearest'}, optional
+        interpolation method for sampling the volume. 'linear' performs trilinear 
+        interpolation (smoother, good for continuous t-stats), while 'nearest' 
+        snaps to the closest voxel center (strictly required for p-values or atlases). 
+        default is 'linear'.
+
+    Returns
+    -------
+    lh_data : numpy.ndarray
+        1D array of projected values for the left hemisphere vertices.
+    rh_data : numpy.ndarray
+        1D array of projected values for the right hemisphere vertices.
+    """
+    from .data import get_surface_paths
+    from .mesh import load_bmesh, extract_polydata
+
+    # load volume
+    img = nib.load(nii_path)
+    vol_data = img.get_fdata()
+    
+    if vol_data.ndim > 3:
+        warnings.warn(f"[WARNING] detected {vol_data.ndim}d nifti volume. using the first volume (index 0).")
+        vol_data = vol_data[..., 0] 
+        
+    inv_affine = np.linalg.inv(img.affine)
+
+    # load brain mesh
+    loaded_meshes = load_bmesh(bmesh)
+    
+    if 'L' not in loaded_meshes or 'R' not in loaded_meshes:
+        raise ValueError("project_vol2surf requires both 'L' and 'R' hemispheres in the bmesh dictionary.")
+        
+    # extract raw coordinates for math
+    lh_v, _ = extract_polydata(loaded_meshes['L'])
+    rh_v, _ = extract_polydata(loaded_meshes['R'])
+
+    def sample_surface(vertices, volume, inv_aff, interp):
+        # convert [x, y, z] to [x, y, z, 1] to allow 4x4 affine matrix multiplication
+        coords_homo = np.hstack((vertices, np.ones((vertices.shape[0], 1))))
+        # multiply by inverse affine to get exact decimal voxel coordinates
+        vox_coords = inv_aff.dot(coords_homo.T)[:3, :]
+        # set scipy interpolation order (1 = trilinear, 0 = nearest neighbor)
+        order = 1 if interp == 'linear' else 0
+        # sample the 3d volume at the calculated decimal coordinates
+        return map_coordinates(volume, vox_coords, order=order, mode='nearest')
+
+    # projection
+    lh_data = sample_surface(lh_v, vol_data, inv_affine, interpolation)
+    rh_data = sample_surface(rh_v, vol_data, inv_affine, interpolation)
+
+    # handle the medial wall
+    if mask_medial_wall:
+        if isinstance(bmesh, str):
+            # only if standard fs_LR 32k mesh
+            lh_mask_path, rh_mask_path = get_surface_paths('nomedialwall', 'label')
+            lh_data[nib.load(lh_mask_path).darrays[0].data == 0] = np.nan
+            rh_data[nib.load(rh_mask_path).darrays[0].data == 0] = np.nan
+        else:
+            warnings.warn("[WARNING] medial wall masking is only automatically supported for standard yabplot string meshes. skipping mask.")
+
+    return lh_data, rh_data
+
+
+def project_vol2tract_atlas(nii_path, atlas='xtract_tiny', custom_atlas_path=None, interpolation='linear'):
+    """
+    Samples a 3D volume across all tracts in a specific atlas.
+    This is a convenience function around `project_vol2tract` that automatically 
+    resolves the atlas paths, loops through all available tractograms, and returns 
+    a dictionary ready to be passed directly to `plot_tracts`.
+
+    Parameters
+    ----------
+    nii_path : str
+        absolute path to the 3D nifti volume (e.g., FA or MD map).
+    atlas : str, optional
+        name of the standard tract atlas. default is 'xtract_tiny'.
+    custom_atlas_path : str, optional
+        path to a custom directory of .trk files.
+    interpolation : {'linear', 'nearest'}, optional
+        trilinear interpolation (default) blends nearby voxels for a smooth map.
+
+    Returns
+    -------
+    dict
+        dictionary mapping tract names to their 1D sampled data arrays.
+    """
+    from .data import _resolve_resource_path, _find_tract_files
+    
+    # resolve the atlas directory and locate all tract files
+    atlas_dir = _resolve_resource_path(atlas, 'tracts', custom_path=custom_atlas_path)
+    tract_files = _find_tract_files(atlas_dir)
+    
+    tract_data = {}
+    
+    # loop through and map the volume to each tract
+    for name, trk_path in tract_files.items():
+        tract_data[name] = project_vol2tract(trk_path, nii_path, interpolation)
+        
+    return tract_data
+
+
+def project_vol2tract(trk_path, nii_path, interpolation='linear'):
+    """
+    Samples a 3D volume natively at every vertex of a tractogram. Maps the streamline 
+    coordinates directly into the volumetric voxel space using the image affine.
+
+    Parameters
+    ----------
+    trk_path : str
+        absolute path to the .trk or .tck tractography file.
+    nii_path : str
+        absolute path to the 3D nifti volume (e.g., FA or MD map).
+    interpolation : {'linear', 'nearest'}, optional
+        trilinear interpolation (default) blends nearby voxels for a smooth map.
+
+    Returns
+    -------
+    numpy.ndarray
+        1D array of sampled values corresponding exactly to the flattened 
+        points of the tractogram, ready to be injected into plot_tracts.
+    """
+    # load the 3D volume
+    img = nib.load(nii_path)
+    vol_data = img.get_fdata()
+    if vol_data.ndim > 3:
+        vol_data = vol_data[..., 0]
+        
+    inv_affine = np.linalg.inv(img.affine)
+
+    # load the tractogram
+    trk = nib.streamlines.load(trk_path)
+    
+    # stack all streamline coordinates into a single (n_points, 3) array
+    points = np.vstack(trk.streamlines)
+    
+    # convert coordinates using the inverse affine
+    coords_homo = np.hstack((points, np.ones((points.shape[0], 1))))
+    vox_coords = inv_affine.dot(coords_homo.T)[:3, :]
+    
+    # sample the volume
+    order = 1 if interpolation == 'linear' else 0
+    sampled_data = map_coordinates(vol_data, vox_coords, order=order, mode='nearest')
+    
+    return sampled_data

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/scene.py

@@ -102,7 +102,7 @@ def add_context_to_view(plotter, bmesh, view_side, alpha, color, **kwargs):
     """
     if not bmesh: return
     for h, mesh in bmesh.items():
-        if (view_side == 'L' and h == 'L') or (view_side == 'R' and h == 'R'): continue
+        if (view_side == 'L' and h == 'R') or (view_side == 'R' and h == 'L'): continue
         plotter.add_mesh(mesh, color=color, opacity=alpha, 
                          smooth_shading=True, show_edges=False, 
                          **kwargs)
@@ -137,6 +137,7 @@ def add_colorbars(plotter, mappers, titles, nrows, figsize):
     
     if num_bars == 1: 
         positions_y = [0.15] 
+        cb_height = 0.4
     elif num_bars == 2: 
         positions_y = [0.5, 0.01]
     else: 
@@ -147,7 +148,7 @@ def add_colorbars(plotter, mappers, titles, nrows, figsize):
             mapper=mapper, title=title, vertical=False, 
             position_x=pos_x, position_y=positions_y[i], 
             height=cb_height, width=cb_width, color='black', 
-            title_font_size=13, label_font_size=11, n_labels=5, fmt="%.2f"
+            title_font_size=13, label_font_size=11, n_labels=3, fmt="%g"
         )
 
 def finalize_plot(plotter, export_path, display_type):

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot/utils.py

@@ -3,6 +3,7 @@ import pandas as pd
 import nibabel as nib
 import pyvista as pv
 import matplotlib.pyplot as plt
+import os
 
 def load_gii(gii_path):
     """Load GIfTI geometry (vertices, faces)."""
@@ -55,11 +56,9 @@ def prep_data(data, regions, atlas, category):
     """Standardize input data to dictionary."""
     if isinstance(data, pd.DataFrame):
         if data.shape[1] >= 2:
-            return dict(zip(data.iloc[:, 0], data.iloc[:, 1]))
+            data = dict(zip(data.iloc[:, 0], data.iloc[:, 1]))
     elif isinstance(data, pd.Series):
-        return data.to_dict()
-    elif isinstance(data, dict):
-        return data
+        data = data.to_dict()
     elif isinstance(data, (list, np.ndarray, tuple)):
         if len(data) != len(regions):
             raise ValueError(
@@ -69,7 +68,13 @@ def prep_data(data, regions, atlas, category):
                 f"Use `yabplot.get_atlas_regions('{atlas}', '{category}')` to see expected order."
             )
         # map strictly by order
-        return dict(zip(regions, data))
+        data = dict(zip(regions, data))
+
+    #resolve any present tsf paths:
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, str):
+                data[key] = read_tsf(value)
 
     return data
 
@@ -105,3 +110,84 @@ def parse_lut(lut_path):
         
     return ids, lut_colors, lut_names_list, max_id
 
+
+def load_tsf(tsf_path: str) -> np.ndarray:
+    """
+    Reads an MRtrix3 .tsf (track scalar file). Useful for users who 
+    have already computed tractometry metrics using MRtrix3's `tcksample` 
+    command and want to plot the resulting values in yabplot.
+    
+    Parameters
+    ----------
+    tsf_path : str
+        absolute path to the .tsf file.
+        
+    Returns
+    -------
+    numpy.ndarray
+        1D array of scalar values for the streamlines.
+    """
+    if not os.path.isfile(tsf_path):
+        raise FileNotFoundError(f"File not found: {tsf_path}")
+    
+    header: dict[str, str] = {}
+    data_offset: int | None = None
+
+    with open(tsf_path, "rb") as fh:
+        # first line must be the magic string
+        magic_line = fh.readline().decode("ascii", errors="replace").strip()
+        if not magic_line.lower().startswith("mrtrix track scalars"):
+            raise ValueError(
+                "Not a valid MRtrix TSF file (missing 'mrtrix track scalars' magic)."
+            )
+        header["magic"] = magic_line
+
+        while True:
+            line = fh.readline()
+            if not line:
+                raise ValueError("Unexpected end of file while reading header.")
+            line = line.decode("ascii", errors="replace").strip()
+            if line == "END":
+                break
+
+            # parse "key: value" pairs
+            colon_pos = line.find(":")
+            if colon_pos > 0:
+                key = line[:colon_pos].strip()
+                value = line[colon_pos + 1 :].strip()
+                header[key] = value
+
+                # capture the data offset
+                if key.lower() == "file":
+                    parts = value.split()
+                    data_offset = int(parts[-1])
+
+        if data_offset is None:
+            raise ValueError("Could not determine data offset from header.")
+
+        # read the binary data
+        fh.seek(data_offset)
+        raw_bytes = fh.read()
+
+    # determine byte order from header
+    datatype = header.get("datatype", "Float32LE").lower()
+    byte_order = ">" if datatype.endswith("be") else "<"
+
+    if "64" in datatype:
+        dtype = np.dtype(f"{byte_order}f8")
+    else:
+        dtype = np.dtype(f"{byte_order}f4")
+
+    # trim any trailing bytes that don't fill a complete element
+    element_size = dtype.itemsize
+    usable = len(raw_bytes) - (len(raw_bytes) % element_size)
+    raw_data = np.frombuffer(raw_bytes[:usable], dtype=dtype)
+
+    # split into per-streamline vectors
+    inf_mask = np.isinf(raw_data)
+    inf_indices = np.where(inf_mask)[0]
+    if inf_indices.size > 0:
+        raw_data = raw_data[: inf_indices[0]]
+
+    nan_mask = np.isnan(raw_data)
+    return raw_data[~nan_mask]

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yabplot
-Version: 0.3.0
+Version: 0.4.0
 Summary: yet another brain plot
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -38,7 +38,7 @@ the idea is simple. while there are already amazing visualization tools availabl
 ## features
 
 * **pre-existing atlases:** access many commonly used atlases (schaefer2018, brainnetome, aparc, aseg, musus100, xtract, etc) on demand.
-* [new!] **vertexwise plotting:** project volume (.nii) to cortical surface and plot.
+* **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).
@@ -77,16 +77,12 @@ print(yab.get_available_resources())
 # see the region names for a specific atlas
 print(yab.get_atlas_regions(atlas='aseg', category='subcortical'))
 
-# cortical surfaces
+# cortical surface regions
 atlas = 'aparc'
 dmap1 = {'L_lateraloccipital': 0.265, 'L_postcentral': 0.086, ...}
-dmap2 = {'L_fusiform': 0.218, 'L_supramarginal': 0.119, ...}
 yab.plot_cortical(data=dmap1, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh_type='midthickness', views=['left_lateral', 'left_medial'],
-                  figsize=(600, 300), cmap='viridis', proc_vertices='sharp')
-yab.plot_cortical(data=dmap2, atlas=atlas, vminmax=[-0.1, 0.3], 
-                  bmesh_type='swm', views=['left_lateral', 'left_medial'],
-                  figsize=(1200, 600), cmap='viridis', proc_vertices='sharp')
+                  bmesh='midthickness', views=['left_lateral', 'left_medial'],
+                  figsize=(600, 300), cmap='viridis')
 
 # subcortical structures
 atlas = 'aseg'
@@ -96,12 +92,22 @@ 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')
 
+# vertex-wise surface
+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))
+
 # 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_type='pial',
+                views=['left_lateral', 'anterior', 'superior'], bmesh='pial',
                 bmesh_alpha=0.1, figsize=(1600, 800), cmap='viridis')
 
 ```

{yabplot-0.3.0 → yabplot-0.4.0}/yabplot.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ yabplot/__init__.py
 yabplot/atlas_builder.py
 yabplot/mesh.py
 yabplot/plotting.py
+yabplot/projection.py
 yabplot/scene.py
 yabplot/utils.py
 yabplot/wrappers.py

yabplot-0.3.0/yabplot/data/registry.txt

@@ -1,29 +0,0 @@
-cortical-aparc.zip sha256:9e3e4853c580b6ed7c70a2b398b8ddacfc30e05600f04f722d3b5e8ee28ba119 https://osf.io/5btcf/download
-cortical-brainnetome.zip sha256:fc4bb0043f2efa133771240f9e7178521be4011e76e5cad8102c9c099fce5ef0 https://osf.io/xspn5/download
-cortical-schaefer_100.zip sha256:041c229b900c86f6b80cc44a05dca74bcfccde9aad5d10878da04a184d0f26ba https://osf.io/yxt5p/download
-cortical-schaefer_200.zip sha256:065ee05afa1881a8884bdecee25a062ddd5fd6283bfeaabb59e6eb696f39563f https://osf.io/v45gq/download
-cortical-schaefer_300.zip sha256:5430c66eaef58f008b9e20dd5c59c670c7f7154b02f4b310dda97250331b6eed https://osf.io/9djtr/download
-cortical-schaefer_400.zip sha256:ae2b7011919d49e9930ee5aed1b19731180427f07f0d1c4497130dd9cd5e878d https://osf.io/pzmc5/download
-cortical-schaefer_1000.zip sha256:a10448f101a874499d41bc62508c3af29120634955f48beb282ece9a4cc2bb0e https://osf.io/j9ygz/download
-cortical-aal3.zip sha256:925e475e099b127925e20e6ec4d179b1a58971f2bc32b2a61f56a479f3e8d4fb https://osf.io/z9jxh/download
-subcortical-aseg.zip sha256:a901a7fc6a39f9bdaf2ef2bafbcde1fbc085b225d99e6730c727650d9be047d5 https://osf.io/5cs7y/download
-subcortical-brainnetome_sc.zip sha256:8301fdf6af109af52a2cf9b06d15486345d457b69cb86169ed38332a34a681c0 https://osf.io/2fsg5/download
-subcortical-jhu.zip sha256:b0ca292589a9f041851dba8159bb605a4657323e4305ba1570a304944b28d0de https://osf.io/x5fhg/download
-subcortical-musus100_dbn.zip sha256:1d865832a35570a8c67f79d5049b58c548d25cf4fe1853164c384193b6712e40 https://osf.io/eutmb/download
-subcortical-tian2020_sc.zip sha256:8b5caf8bf0cdcf8e259a3532fbcb232f8746d68fc734ca9806d10e70cf8707a3 https://osf.io/jrvgp/download
-subcortical-aal3.zip sha256:48abe400656d913cc459ee8766e373cc5eabbeb9e4f770aa7396da3d4a0ab3ca https://osf.io/39ebh/download
-subcortical-aal3_nocer.zip sha256:b87de55861cdd18ddb78934964b0e0855f770560bdc878570fcbb8f27fefb674 https://osf.io/7jdxz/download
-tracts-hcp1065_medium.zip sha256:366bb100074cf7b1e55586e5468653f0c342e42cfdd91dca6d99b6fde82f06ff https://osf.io/kjf8e/download
-tracts-hcp1065_small.zip sha256:020f23059c3a20ee0dda8ad12cd3df99b9fe5d3b37e7a6b9ae34b8a52b4b4346 https://osf.io/ynpa5/download
-tracts-hcp1065_tiny.zip sha256:54380d82f5cd234029c6fc011910e00f0ad859fdb6c22c6aaa6452d055449ae9 https://osf.io/jzk7p/download
-tracts-xtract_large.zip sha256:e2d59e9f90b024018788af87e389f93b2fa9ac213604601966a44d7f81c9d89f https://osf.io/pktq6/download
-tracts-xtract_medium.zip sha256:f095028d3dfc0f974ebef1feffe4006b5bac1366325a784ea2301c56f583b1e7 https://osf.io/7tbjg/download
-tracts-xtract_small.zip sha256:9d3fe2c57acb87e8d13eb40a49a6c2c354dbe1a020122b693e9bf713e57cad5b https://osf.io/bmn3a/download
-tracts-xtract_tiny.zip sha256:469f9ed8ed5ceb7f8e17c9a0a92f1491d540814f832ef56441a7539532111f41 https://osf.io/a73x2/download
-bmesh-inflated.zip sha256:ba72f9e75f16fe767f6bbcec5c98381f6a20b2f5e2092505b4692844a1686461 https://osf.io/kfzjg/download
-bmesh-midthickness.zip sha256:ef8209853e1dac8804a60b5cde0b653ef2f6c77b6c7536f7acaa69a46dbb06c0 https://osf.io/xaktf/download
-bmesh-pial.zip sha256:5e36ba7883dd2a88485fc45c9166ed48e22db607d45655242961242b51f9f126 https://osf.io/knpg8/download
-bmesh-swm.zip sha256:1a516c070cb63557751d841d5cf75772660872b89ec749ee19c23298d77fa807 https://osf.io/hpbc9/download
-bmesh-very_inflated.zip sha256:8c33a00c718a47f0af118ce2c5804a2adf13d79be05c4665ca26582e3e8dd977 https://osf.io/xp9jr/download
-bmesh-white.zip sha256:b885ac1a4dcdf9e241a97e8d3ca59d7b1c86d8a3ebe17df512993bc5c1c0354a https://osf.io/wfc5t/download
-label-nomedialwall.zip sha256:03bd589b151814a1fc5e48236a78decf1a51791f04c3f4a521d2ed4fb214317b https://osf.io/2rgmc/download