PyNutil 0.5.1__tar.gz → 0.5.4__tar.gz

{pynutil-0.5.1 → pynutil-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyNutil
-Version: 0.5.1
+Version: 0.5.4
 Summary: a package to quantify atlas registered brain data
 Home-page: https://github.com/Neural-Systems-at-UIO/PyNutil
 License: MIT
@@ -26,7 +26,9 @@ Dynamic: summary
 
 # PyNutil
 
-## PyNutil is still under development and the API is subject to change 
+> [!WARNING]  
+> PyNutil is still under development and the API is subject to change.
+
 
 PyNutil is a Python library for brain-wide quantification and spatial analysis of features in serial section images from the brain. It aims to replicate the Quantifier feature of the Nutil software (RRID: SCR_017183). 
 
@@ -71,37 +73,31 @@ As input, PyNutil requires:
 3. A segmentation file for each brain section with the features to be quantified displayed with a unique RGB colour code (it currently accepts many image formats: png, jpg, jpeg, etc).
 
 ```python
-from PyNutil import PyNutil
-
-"""
-Here we define a quantifier object
-The segmentations should be images which come out of ilastik, segmenting objects-of-interest
-The alignment json should be from DeepSlice, QuickNII, or VisuAlign, it defines the sections position in an atlas
-The colour says which colour is the object you want to quantify in your segmentation. It is defined in RGB
-Finally the atlas name is the relevant atlas from brainglobe_atlasapi or a custom atlas in nrrd format.
-
-basic_example.py (brainglobe_atlasapi)
-basic_example_custom_atlas.py (custom atlas)
-
-"""
-pnt = PyNutil(
-    segmentation_folder='../tests/test_data/non_linear_allen_mouse/segmentations/',
-    alignment_json='../tests/test_data/non_linear_allen_mouse/alignment.json',
-    colour=[0, 0, 0],
-    atlas_name='allen_mouse_25um'
-    #If you would like to use cellpose segmentations add:
-    #segmentation_format = 'cellpose'
+from brainglobe_atlasapi import BrainGlobeAtlas
+import PyNutil as pnt
+
+# Load an atlas (BrainGlobe) and alignment
+atlas = BrainGlobeAtlas("allen_mouse_25um")
+alignment = pnt.read_alignment("path/to/alignment.json")
+
+# Extract coordinates from segmentations
+coords = pnt.seg_to_coords(
+    "path/to/segmentations/",
+    alignment,
+    atlas,
+    pixel_id=[0, 0, 0],
+    # For cellpose segmentations: segmentation_format="cellpose"
 )
 
-#optionally, if you want to generate a 3D heatmap
-pnt.interpolate_volume()
-
-pnt.get_coordinates(object_cutoff=0)
+# Quantify by atlas region
+label_df = pnt.quantify_coords(coords, atlas)
 
-pnt.quantify_coordinates()
-
-pnt.save_analysis("PyNutil/test_result/myResults")
+# Save results
+pnt.save_analysis("path/to/output", coords, atlas, label_df=label_df)
 ```
+
+For custom atlases (not from BrainGlobe), use `pnt.load_custom_atlas()` instead.
+See `demos/basic_example.py` and `demos/basic_example_custom_atlas.py` for complete examples.
 PyNutil generates a series of reports in the folder which you specify.
 
 ## Per-Hemisphere Quantification

pynutil-0.5.4/PyNutil/__init__.py

@@ -0,0 +1,30 @@
+from .results import AtlasData, ExtractionResult, PointSetResult
+from .processing.adapters.base import RegistrationData
+from .processing.adapters import read_alignment
+from .io.atlas_loader import load_atlas_data, load_custom_atlas
+from .processing.pipeline.batch_processor import (
+    seg_to_coords,
+    image_to_coords,
+    xy_to_coords,
+)
+from .processing.analysis.data_analysis import quantify_coords
+from .io.file_operations import save_analysis
+from .processing.section_volume import interpolate_volume
+from .io.volume_nifti import save_volume_niftis
+
+__all__ = [
+    "AtlasData",
+    "ExtractionResult",
+    "PointSetResult",
+    "RegistrationData",
+    "read_alignment",
+    "load_atlas_data",
+    "load_custom_atlas",
+    "seg_to_coords",
+    "image_to_coords",
+    "xy_to_coords",
+    "quantify_coords",
+    "save_analysis",
+    "interpolate_volume",
+    "save_volume_niftis",
+]

{pynutil-0.5.1 → pynutil-0.5.4}/PyNutil/config.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
-import json
 from dataclasses import dataclass
 from typing import Any, Dict, Optional
 
+from .io.loaders import load_json_file
+
 
 @dataclass
 class PyNutilConfig:
@@ -25,8 +26,7 @@ class PyNutilConfig:
 
     @classmethod
     def from_settings_file(cls, settings_file: str) -> "PyNutilConfig":
-        with open(settings_file, "r") as f:
-            settings = json.load(f)
+        settings = load_json_file(settings_file)
         return cls.from_settings_dict(settings)
 
     @classmethod

{pynutil-0.5.1 → pynutil-0.5.4}/PyNutil/context.py

@@ -62,6 +62,43 @@ class PipelineContext:
     min_intensity: Optional[int] = None
     max_intensity: Optional[int] = None
 
+    @classmethod
+    def from_format(
+        cls,
+        *,
+        segmentation_format: str,
+        atlas_labels,
+        atlas_volume,
+        hemi_map,
+        non_linear: bool,
+        object_cutoff: int,
+        use_flat: bool,
+        pixel_id,
+        apply_damage_mask: bool,
+        flat_label_path=None,
+        intensity_channel=None,
+        min_intensity=None,
+        max_intensity=None,
+    ) -> "PipelineContext":
+        """Construct a PipelineContext, resolving *segmentation_format* to an adapter."""
+        from .processing.adapters.segmentation import SegmentationAdapterRegistry
+
+        return cls(
+            atlas_labels=atlas_labels,
+            atlas_volume=atlas_volume,
+            hemi_map=hemi_map,
+            segmentation_adapter=SegmentationAdapterRegistry.get(segmentation_format),
+            non_linear=non_linear,
+            object_cutoff=object_cutoff,
+            use_flat=use_flat,
+            pixel_id=pixel_id,
+            apply_damage_mask=apply_damage_mask,
+            flat_label_path=flat_label_path,
+            intensity_channel=intensity_channel,
+            min_intensity=min_intensity,
+            max_intensity=max_intensity,
+        )
+
 
 @dataclass(frozen=True)
 class SectionContext:

pynutil-0.5.4/PyNutil/io/__init__.py

@@ -0,0 +1,13 @@
+"""PyNutil I/O subpackage.
+
+This package contains modules for reading and writing data:
+- atlas_loader: Loading BrainGlobe and custom atlases
+- file_operations: Saving analysis outputs
+- loaders: File loading (custom regions, flat files, segmentations, JSON)
+- meshview_writer: MeshView JSON output
+- colormap: Colormap utilities
+- section_visualisation: Creating section PNG visualizations
+- volume_nifti: NIfTI volume output
+- propagation: Slice anchoring interpolation
+- reconstruct_dzi: DZI image reconstruction
+"""

pynutil-0.5.4/PyNutil/io/atlas_loader.py

@@ -0,0 +1,131 @@
+import brainglobe_atlasapi
+import pandas as pd
+import numpy as np
+import nrrd
+from functools import lru_cache
+
+from ..results import AtlasData
+
+
+def load_atlas_labels(atlas=None, atlas_name=None):
+    if atlas_name:
+        atlas = brainglobe_atlasapi.BrainGlobeAtlas(atlas_name=atlas_name)
+    if not atlas_name and not atlas:
+        raise Exception("Either atlas or atlas name must be specified")
+    atlas_structures = {
+        "idx": [],
+        "name": [],
+        "r": [],
+        "g": [],
+        "b": [],
+    }
+    for structure in atlas.structures_list:
+        atlas_structures["idx"].append(structure["id"])
+        atlas_structures["name"].append(structure["name"])
+        rgb = structure["rgb_triplet"]
+        atlas_structures["r"].append(rgb[0])
+        atlas_structures["g"].append(rgb[1])
+        atlas_structures["b"].append(rgb[2])
+    atlas_structures["idx"].insert(0, 0)
+    atlas_structures["name"].insert(0, "Clear Label")
+    atlas_structures["r"].insert(0, 0)
+    atlas_structures["g"].insert(0, 0)
+    atlas_structures["b"].insert(0, 0)
+    atlas_labels = pd.DataFrame(atlas_structures)
+    return atlas_labels
+
+
+def resolve_atlas(atlas):
+    """Convert an atlas argument to AtlasData.
+
+    Accepts an ``AtlasData`` instance (returned as-is) or a
+    ``BrainGlobeAtlas``-like object (converted via volume processing and
+    label loading).
+    """
+    if isinstance(atlas, AtlasData):
+        return atlas
+    # Assume BrainGlobeAtlas-like object
+    volume = process_atlas_volume(atlas.annotation)
+    hemi_map = process_atlas_volume(atlas.hemispheres)
+    labels = load_atlas_labels(atlas)
+    return AtlasData(volume=volume, hemi_map=hemi_map, labels=labels)
+
+
+def resolve_atlas_labels(atlas_labels):
+    """Resolve atlas labels input into a DataFrame.
+
+    Accepts a raw labels DataFrame, AtlasData-like objects exposing ``labels``,
+    or BrainGlobeAtlas-like objects exposing ``structures_list``.
+    """
+    if isinstance(atlas_labels, pd.DataFrame):
+        return atlas_labels
+    if hasattr(atlas_labels, "labels"):
+        return atlas_labels.labels
+    if hasattr(atlas_labels, "structures_list"):
+        return load_atlas_labels(atlas_labels)
+    raise TypeError(
+        "atlas_labels must be a pandas DataFrame, AtlasData-like (.labels), "
+        "or BrainGlobeAtlas-like (.structures_list)."
+    )
+
+
+@lru_cache(maxsize=8)
+def load_atlas_data(atlas_name):
+    """
+    Loads atlas data using the brainglobe_atlasapi.
+
+    Parameters
+    ----------
+    atlas_name : str
+        Name of the atlas to load.
+
+    Returns
+    -------
+    AtlasData
+        Bundle containing atlas volume, hemisphere map, and labels.
+    """
+    atlas = brainglobe_atlasapi.BrainGlobeAtlas(atlas_name=atlas_name)
+    atlas_labels = load_atlas_labels(atlas)
+    atlas_volume = process_atlas_volume(atlas.annotation)
+    hemi_map = process_atlas_volume(atlas.hemispheres)
+    print("atlas labels loaded ✅")
+    return AtlasData(volume=atlas_volume, hemi_map=hemi_map, labels=atlas_labels)
+
+
+def process_atlas_volume(vol):
+    """
+    Processes the atlas volume by transposing and reversing axes.
+
+    Parameters
+    ----------
+    vol : numpy.ndarray
+        The atlas volume to process.
+
+    Returns
+    -------
+    numpy.ndarray
+        The processed atlas volume.
+    """
+    return np.transpose(vol, [2, 0, 1])[::-1, ::-1, ::-1]
+
+
+@lru_cache(maxsize=8)
+def load_custom_atlas(atlas_path, hemi_path, label_path):
+    """
+    Loads a custom atlas from provided file paths.
+
+    Returns
+    -------
+    AtlasData
+        Bundle containing atlas volume, hemisphere map, and labels.
+    """
+    atlas_volume, _ = nrrd.read(atlas_path)
+
+    if hemi_path:
+        hemi_volume, _ = nrrd.read(hemi_path)
+    else:
+        hemi_volume = None
+
+    atlas_labels = pd.read_csv(label_path)
+
+    return AtlasData(volume=atlas_volume, hemi_map=hemi_volume, labels=atlas_labels)

{pynutil-0.5.1 → pynutil-0.5.4}/PyNutil/io/colormap.py

@@ -6,8 +6,6 @@ intensity values to RGB colors, avoiding matplotlib dependency.
 
 from __future__ import annotations
 
-from typing import Tuple
-
 import numpy as np
 
 
@@ -71,24 +69,3 @@ def get_colormap_colors(values: np.ndarray, name: str = "gray") -> np.ndarray:
     lut = _build_lut(name)
     idx = np.clip(values, 0, 255).astype(np.intp)
     return lut[idx]
-
-
-def get_colormap_color(value: int, name: str = "gray") -> Tuple[int, int, int]:
-    """Map an intensity value (0-255) to RGB color based on colormap name.
-
-    Parameters
-    ----------
-    value : int
-        Intensity value (0-255).
-    name : str
-        Colormap name. Options: "gray", "viridis", "plasma", "magma", "hot".
-
-    Returns
-    -------
-    tuple
-        (r, g, b) color values (0-255).
-    """
-    lut = _build_lut(name)
-    idx = int(np.clip(value, 0, 255))
-    row = lut[idx]
-    return int(row[0]), int(row[1]), int(row[2])

pynutil-0.5.4/PyNutil/io/file_operations.py

@@ -0,0 +1,171 @@
+import os
+import json
+from dataclasses import dataclass
+from typing import Optional, Dict, Any
+
+import numpy as np
+import pandas as pd
+
+from .meshview_writer import write_hemi_points_to_meshview
+from .atlas_loader import resolve_atlas_labels
+
+
+@dataclass
+class SaveContext:
+    """Groups the parameters needed by :func:`save_analysis_output`."""
+
+    # Core data
+    points: Optional[np.ndarray] = None
+    objects: Optional[np.ndarray] = None
+    label_df: Optional[pd.DataFrame] = None
+    point_labels: Optional[np.ndarray] = None
+    object_labels: Optional[np.ndarray] = None
+    points_hemi_labels: Optional[np.ndarray] = None
+    objects_hemi_labels: Optional[np.ndarray] = None
+    atlas_labels: Optional[pd.DataFrame] = None
+    point_values: Optional[np.ndarray] = None
+
+    # Whether this is intensity mode (affects report filename)
+    is_intensity: bool = False
+
+    # Settings dict written to pynutil_settings.json (optional)
+    settings_dict: Optional[Dict[str, Any]] = None
+
+    # Output control
+    prepend: str = ""
+    colormap: str = "gray"
+
+
+def _ensure_analysis_output_dirs(output_folder: str) -> None:
+    os.makedirs(output_folder, exist_ok=True)
+    for subdir in (
+        "whole_series_report",
+        "whole_series_meshview",
+    ):
+        os.makedirs(f"{output_folder}/{subdir}", exist_ok=True)
+
+
+def save_analysis_output(ctx: SaveContext, output_folder: str):
+    """
+    Save the analysis output to the specified folder.
+
+    Parameters
+    ----------
+    ctx : SaveContext
+        All data and configuration needed for saving.
+    output_folder : str
+        The folder where the output will be saved.
+    """
+    # Create the output folder if it doesn't exist
+    _ensure_analysis_output_dirs(output_folder)
+
+    if ctx.label_df is not None:
+        report_name = "intensity.csv" if ctx.is_intensity else "counts.csv"
+        ctx.label_df.to_csv(
+            f"{output_folder}/whole_series_report/{ctx.prepend}{report_name}",
+            sep=";",
+            na_rep="",
+            index=False,
+        )
+    elif not ctx.prepend:
+        print("No quantification found, so only coordinates will be saved.")
+        print(
+            "If you want to save the quantification, please run quantify_coordinates."
+        )
+
+    if ctx.points is not None:
+        _save_whole_series_meshview(ctx, output_folder)
+
+    _save_settings_json(ctx, output_folder)
+
+
+def _save_settings_json(ctx: SaveContext, output_folder: str) -> None:
+    """Write a reference settings JSON to *output_folder*."""
+    if ctx.settings_dict is None:
+        return
+    settings_file_path = os.path.join(output_folder, "pynutil_settings.json")
+    with open(settings_file_path, "w") as f:
+        json.dump(ctx.settings_dict, f, indent=4)
+
+
+def _save_whole_series_meshview(ctx: SaveContext, output_folder: str):
+    """Write whole-series MeshView JSONs for pixels and centroids."""
+    write_hemi_points_to_meshview(
+        ctx.points,
+        ctx.point_labels,
+        ctx.points_hemi_labels,
+        f"{output_folder}/whole_series_meshview/{ctx.prepend}pixels_meshview.json",
+        ctx.atlas_labels,
+        ctx.point_values,
+        colormap=ctx.colormap,
+    )
+    if ctx.objects is not None:
+        write_hemi_points_to_meshview(
+            ctx.objects,
+            ctx.object_labels,
+            ctx.objects_hemi_labels,
+            f"{output_folder}/whole_series_meshview/{ctx.prepend}objects_meshview.json",
+            ctx.atlas_labels,
+            colormap=ctx.colormap,
+        )
+
+
+def save_analysis(
+    output_folder,
+    result,
+    atlas_labels,
+    label_df=None,
+    *,
+    colormap="gray",
+    settings_dict=None,
+):
+    """Save analysis output to the specified directory.
+
+    Args:
+        output_folder: Directory to write output files.
+        result: ExtractionResult from coordinate extraction.
+        atlas_labels: Atlas labels DataFrame (or AtlasData — ``.labels`` used).
+        label_df: Whole-series quantification DataFrame.
+        colormap: Colormap for MeshView intensity output.
+        settings_dict: Optional dict written to pynutil_settings.json.
+    """
+    atlas_labels = resolve_atlas_labels(atlas_labels)
+
+    ctx = SaveContext(
+        points=result.points.filtered_points() if result else None,
+        objects=(
+            result.objects.filtered_points()
+            if (result and result.objects is not None)
+            else None
+        ),
+        label_df=label_df,
+        point_labels=result.points.filtered_labels() if result else None,
+        object_labels=(
+            result.objects.filtered_labels()
+            if (result and result.objects is not None)
+            else None
+        ),
+        points_hemi_labels=result.points.filtered_hemi_labels() if result else None,
+        objects_hemi_labels=(
+            result.objects.filtered_hemi_labels()
+            if (result and result.objects is not None)
+            else None
+        ),
+        atlas_labels=atlas_labels,
+        point_values=result.points.filtered_point_values() if result else None,
+        is_intensity=result.region_intensities is not None if result else False,
+        settings_dict=settings_dict,
+        colormap=colormap,
+    )
+    save_analysis_output(ctx, output_folder)
+
+    # Remap compressed IDs if present
+    if label_df is not None and "original_idx" in label_df.columns:
+        remapped = label_df.copy()
+        remapped["idx"] = remapped["original_idx"]
+        remapped = remapped.drop(columns=["original_idx"])
+        remapped.to_csv(
+            f"{output_folder}/whole_series_report/counts.csv",
+            sep=";",
+            index=False,
+        )