PyNutil 0.3.3__tar.gz → 0.4.2__tar.gz

{pynutil-0.3.3 → pynutil-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyNutil
-Version: 0.3.3
+Version: 0.4.2
 Summary: a package to quantify atlas registered brain data
 Home-page: https://github.com/Neural-Systems-at-UIO/PyNutil
 License: MIT
@@ -14,6 +14,7 @@ Requires-Dist: xmltodict
 Requires-Dist: opencv-python
 Requires-Dist: scipy
 Requires-Dist: nibabel
+Requires-Dist: orjson
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: home-page
@@ -23,9 +24,8 @@ Dynamic: requires-dist
 Dynamic: summary
 
 # PyNutil
-PyNutil is under development. 
 
-**Warning:** There are known errors in the PyNutil reports (incorrect results). Please use Nutil until these are fixed. 
+## 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). 
 
@@ -89,7 +89,7 @@ pnt = PyNutil(
     colour=[0, 0, 0],
     atlas_name='allen_mouse_25um'
     #If you would like to use cellpose segmentations add:
-    #cellpose = True
+    #segmentation_format = 'cellpose'
 )
 
 #optionally, if you want to generate a 3D heatmap
@@ -139,6 +139,7 @@ Each column name has the following definition
 | Right hemi    | For each of the other columns, what is that value for the right hemisphere alone    |
 | Damaged       | For each of the other columns, what is that value for the areas marked damaged alone|
 | Undamaged     | For each of the other columns, what is that value for the areas marked undamaged alone|
+
 If you choose to measure the intensity of images rather than segmentations you will not get object counts. Instead you will get
 | Column        | Definition                                                                          |
 |---------------|-------------------------------------------------------------------------------------|

{pynutil-0.3.3 → pynutil-0.4.2}/PyNutil/config.py

@@ -5,13 +5,6 @@ from dataclasses import dataclass
 from typing import Any, Dict, Optional
 
 
-def _unwrap_singleton_list(value: Any) -> Any:
-    """Unwrap legacy settings fields like [null] -> None, ["x"] -> "x"."""
-    if isinstance(value, list) and len(value) == 1:
-        return value[0]
-    return value
-
-
 @dataclass
 class PyNutilConfig:
     segmentation_folder: Optional[str] = None
@@ -27,7 +20,7 @@ class PyNutilConfig:
     voxel_size_um: Optional[float] = None
     min_intensity: Optional[int] = None
     max_intensity: Optional[int] = None
-    cellpose: bool = False
+    segmentation_format: str = "binary"  # "binary" or "cellpose"
 
     @classmethod
     def from_settings_file(cls, settings_file: str) -> "PyNutilConfig":
@@ -37,10 +30,6 @@ class PyNutilConfig:
 
     @classmethod
     def from_settings_dict(cls, settings: Dict[str, Any]) -> "PyNutilConfig":
-        # Be tolerant of legacy settings saved as singleton lists.
-        def g(key: str, default: Any = None) -> Any:
-            return _unwrap_singleton_list(settings.get(key, default))
-
         # alignment_json is required in settings files.
         if "alignment_json" not in settings:
             raise KeyError(
@@ -48,20 +37,20 @@ class PyNutilConfig:
             )
 
         cfg = cls(
-            segmentation_folder=g("segmentation_folder"),
-            image_folder=g("image_folder"),
+            segmentation_folder=settings.get("segmentation_folder"),
+            image_folder=settings.get("image_folder"),
             alignment_json=settings["alignment_json"],
-            colour=g("colour"),
-            intensity_channel=g("intensity_channel"),
-            atlas_name=g("atlas_name"),
-            atlas_path=g("atlas_path"),
-            label_path=g("label_path"),
-            hemi_path=g("hemi_path"),
-            custom_region_path=g("custom_region_path"),
-            voxel_size_um=g("voxel_size_um"),
-            min_intensity=g("min_intensity"),
-            max_intensity=g("max_intensity"),
-            cellpose=bool(g("cellpose", False)),
+            colour=settings.get("colour"),
+            intensity_channel=settings.get("intensity_channel"),
+            atlas_name=settings.get("atlas_name"),
+            atlas_path=settings.get("atlas_path"),
+            label_path=settings.get("label_path"),
+            hemi_path=settings.get("hemi_path"),
+            custom_region_path=settings.get("custom_region_path"),
+            voxel_size_um=settings.get("voxel_size_um"),
+            min_intensity=settings.get("min_intensity"),
+            max_intensity=settings.get("max_intensity"),
+            segmentation_format=settings.get("segmentation_format", "binary"),
         )
 
         # If atlas_path/label_path are present but empty/null, treat as not provided.
@@ -84,6 +73,10 @@ class PyNutilConfig:
         return self
 
     def validate(self) -> None:
+        self._validate_folders()
+        self._validate_atlas()
+
+    def _validate_folders(self) -> None:
         if self.segmentation_folder and self.image_folder:
             raise ValueError(
                 "Please specify either segmentation_folder or image_folder, not both."
@@ -101,6 +94,7 @@ class PyNutilConfig:
                 "You can't specify both colour and image_folder since there are no segmentations"
             )
 
+    def _validate_atlas(self) -> None:
         if (self.atlas_path or self.label_path) and self.atlas_name:
             raise ValueError(
                 "Please specify either atlas_path and label_path or atlas_name. Atlas and label paths are only used for loading custom atlases."

pynutil-0.4.2/PyNutil/context.py

@@ -0,0 +1,84 @@
+"""Immutable context objects for pipeline orchestration.
+
+These frozen dataclasses carry state through the batch and section
+processing layers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+import numpy as np
+import pandas as pd
+
+from .processing.adapters.base import SliceInfo
+from .processing.adapters.segmentation import SegmentationAdapter
+
+
+@dataclass(frozen=True)
+class PipelineContext:
+    """Immutable state shared across all sections in a batch run.
+
+    Attributes
+    ----------
+    atlas_labels : pd.DataFrame
+        Region lookup table (idx, name, r, g, b …).
+    atlas_volume : np.ndarray or None
+        3-D annotation volume for atlas-based slicing.
+    hemi_map : np.ndarray or None
+        3-D hemisphere mask (same shape as *atlas_volume*).
+    segmentation_adapter : SegmentationAdapter
+        Pre-resolved adapter for the current segmentation format.
+    non_linear : bool
+        Whether to apply non-linear deformation.
+    object_cutoff : int
+        Minimum connected-component area (binary pipeline).
+    use_flat : bool
+        If True, load flat-file atlas maps instead of slicing the volume.
+    pixel_id : object
+        Pixel colour to match, or ``"auto"`` for auto-detection.
+    apply_damage_mask : bool
+        Apply the damage / exclusion mask when available.
+    intensity_channel : str or None
+        Channel name for the intensity pipeline (``None`` in binary mode).
+    min_intensity : int or None
+        Lower intensity bound (intensity pipeline only).
+    max_intensity : int or None
+        Upper intensity bound (intensity pipeline only).
+    """
+
+    atlas_labels: pd.DataFrame
+    atlas_volume: Optional[np.ndarray]
+    hemi_map: Optional[np.ndarray]
+    segmentation_adapter: SegmentationAdapter
+    non_linear: bool
+    object_cutoff: int
+    use_flat: bool
+    pixel_id: object
+    apply_damage_mask: bool
+    intensity_channel: Optional[str] = None
+    min_intensity: Optional[int] = None
+    max_intensity: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class SectionContext:
+    """Immutable per-section state built inside the batch loop.
+
+    Attributes
+    ----------
+    section_number : int
+        Numeric section identifier matching the alignment JSON.
+    slice_info : SliceInfo
+        Registration data for this section (anchoring, deformation, damage …).
+    segmentation_path : str
+        Path to the segmentation / image file on disk.
+    flat_file_path : str or None
+        Path to the corresponding flat-file atlas, if any.
+    """
+
+    section_number: int
+    slice_info: SliceInfo
+    segmentation_path: str
+    flat_file_path: Optional[str] = None

pynutil-0.4.2/PyNutil/io/__init__.py

@@ -0,0 +1,63 @@
+"""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
+"""
+
+from .atlas_loader import (
+    load_atlas_data,
+    load_atlas_labels,
+    load_custom_atlas,
+    process_atlas_volume,
+)
+from .file_operations import save_analysis_output, SaveContext
+from .loaders import (
+    load_quint_json,
+    load_segmentation,
+    number_sections,
+    get_flat_files,
+    get_current_flat_file,
+    open_custom_region_file,
+    read_flat_file,
+    read_seg_file,
+)
+from .meshview_writer import (
+    create_region_dict,
+    write_hemi_points_to_meshview,
+    write_points_to_meshview,
+)
+from .colormap import get_colormap_color
+from .volume_nifti import save_volume_niftis
+
+__all__ = [
+    # atlas_loader
+    "load_atlas_data",
+    "load_atlas_labels",
+    "load_custom_atlas",
+    "process_atlas_volume",
+    # file_operations
+    "save_analysis_output",
+    "SaveContext",
+    # loaders
+    "load_quint_json",
+    "load_segmentation",
+    "open_custom_region_file",
+    "read_flat_file",
+    "read_seg_file",
+    # meshview_writer
+    "create_region_dict",
+    "write_hemi_points_to_meshview",
+    "write_points_to_meshview",
+    # colormap
+    "get_colormap_color",
+    # volume_nifti
+    "save_volume_niftis",
+]

pynutil-0.4.2/PyNutil/io/colormap.py

@@ -0,0 +1,94 @@
+"""Colormap utilities for PyNutil.
+
+This module provides simple colormap implementations for mapping
+intensity values to RGB colors, avoiding matplotlib dependency.
+"""
+
+from __future__ import annotations
+
+from typing import Tuple
+
+import numpy as np
+
+
+def _viridis(t):
+    return 1.0 - t, t, 0.5 + 0.5 * t
+
+
+def _plasma(t):
+    return t, 1.0 - t, 1.0 - 0.5 * t
+
+
+def _magma(t):
+    return t, t**2, 1.0 - t
+
+
+def _hot(t):
+    return (
+        np.minimum(1.0, t * 3),
+        np.minimum(1.0, np.maximum(0.0, t * 3 - 1)),
+        np.minimum(1.0, np.maximum(0.0, t * 3 - 2)),
+    )
+
+
+_COLORMAPS = {
+    "viridis": _viridis,
+    "plasma": _plasma,
+    "magma": _magma,
+    "hot": _hot,
+}
+
+# Pre-built 256-entry LUT cache:  {name: (N, 3) uint8 array}
+_LUT_CACHE: dict[str, np.ndarray] = {}
+
+
+def _build_lut(name: str) -> np.ndarray:
+    """Build a (256, 3) uint8 lookup table for *name*."""
+    if name in _LUT_CACHE:
+        return _LUT_CACHE[name]
+    t = np.arange(256, dtype=np.float64) / 255.0
+    fn = _COLORMAPS.get(name)
+    if fn is None:
+        # gray
+        v = np.arange(256, dtype=np.uint8)
+        lut = np.column_stack([v, v, v])
+    else:
+        r, g, b = fn(t)
+        lut = np.column_stack([
+            np.clip(np.asarray(r) * 255, 0, 255).astype(np.uint8),
+            np.clip(np.asarray(g) * 255, 0, 255).astype(np.uint8),
+            np.clip(np.asarray(b) * 255, 0, 255).astype(np.uint8),
+        ])
+    _LUT_CACHE[name] = lut
+    return lut
+
+
+def get_colormap_colors(values: np.ndarray, name: str = "gray") -> np.ndarray:
+    """Vectorised colormap lookup for an array of intensity values (0-255).
+
+    Returns a (N, 3) uint8 array of RGB colours.
+    """
+    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.4.2/PyNutil/io/file_operations.py

@@ -0,0 +1,221 @@
+import os
+import json
+from dataclasses import dataclass
+from typing import Optional, List
+
+import numpy as np
+import pandas as pd
+
+from .meshview_writer import write_hemi_points_to_meshview
+
+
+@dataclass
+class SaveContext:
+    """Groups the many parameters needed by :func:`save_analysis_output`.
+
+    Replaces 26+ positional parameters with a single, documented object.
+    """
+
+    # Core data
+    pixel_points: Optional[np.ndarray] = None
+    centroids: Optional[np.ndarray] = None
+    label_df: Optional[pd.DataFrame] = None
+    per_section_df: Optional[list] = None
+    labeled_points: Optional[np.ndarray] = None
+    labeled_points_centroids: Optional[np.ndarray] = None
+    points_hemi_labels: Optional[np.ndarray] = None
+    centroids_hemi_labels: Optional[np.ndarray] = None
+    points_len: Optional[list] = None
+    centroids_len: Optional[list] = None
+    segmentation_filenames: Optional[list] = None
+    atlas_labels: Optional[pd.DataFrame] = None
+    point_intensities: Optional[np.ndarray] = None
+
+    # Configuration / metadata (saved to settings JSON)
+    segmentation_folder: Optional[str] = None
+    image_folder: Optional[str] = None
+    alignment_json: Optional[str] = None
+    colour: Optional[list] = None
+    intensity_channel: Optional[str] = None
+    atlas_name: Optional[str] = None
+    custom_region_path: Optional[str] = None
+    atlas_path: Optional[str] = None
+    label_path: Optional[str] = None
+    settings_file: Optional[str] = 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",
+        "per_section_meshview",
+        "per_section_reports",
+        "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.image_folder 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.per_section_df is not None and ctx.segmentation_filenames is not None:
+        _save_per_section_reports(ctx, output_folder)
+    if ctx.pixel_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*."""
+    settings_dict = {
+        "segmentation_folder": ctx.segmentation_folder,
+        "image_folder": ctx.image_folder,
+        "alignment_json": ctx.alignment_json,
+        "colour": ctx.colour,
+        "intensity_channel": ctx.intensity_channel,
+        "custom_region_path": ctx.custom_region_path,
+    }
+
+    for key, val in [
+        ("atlas_name", ctx.atlas_name),
+        ("atlas_path", ctx.atlas_path),
+        ("label_path", ctx.label_path),
+        ("settings_file", ctx.settings_file),
+    ]:
+        if val:
+            settings_dict[key] = val
+
+    settings_file_path = os.path.join(output_folder, "pynutil_settings.json")
+    with open(settings_file_path, "w") as f:
+        json.dump(settings_dict, f, indent=4)
+
+
+def _save_per_section_reports(ctx: SaveContext, output_folder: str):
+    """Write per-section CSVs and MeshView JSONs."""
+    prev_pl = 0
+    prev_cl = 0
+
+    # Handle None for points_len and centroids_len (e.g. in intensity mode)
+    points_len = ctx.points_len or [0] * len(ctx.segmentation_filenames)
+    centroids_len = ctx.centroids_len or [0] * len(ctx.segmentation_filenames)
+
+    for pl, cl, fn, df in zip(
+        points_len,
+        centroids_len,
+        ctx.segmentation_filenames,
+        ctx.per_section_df,
+    ):
+        split_fn = fn.split(os.sep)[-1].split(".")[0]
+        df.to_csv(
+            f"{output_folder}/per_section_reports/{ctx.prepend}{split_fn}.csv",
+            sep=";",
+            na_rep="",
+            index=False,
+        )
+        if ctx.pixel_points is not None or ctx.centroids is not None:
+            section_intensities = (
+                ctx.point_intensities[prev_pl : pl + prev_pl]
+                if ctx.point_intensities is not None
+                else None
+            )
+            _save_per_section_meshview(
+                ctx,
+                output_folder,
+                split_fn,
+                pl,
+                cl,
+                prev_pl,
+                prev_cl,
+                section_intensities,
+            )
+        prev_cl += cl
+        prev_pl += pl
+
+
+def _save_per_section_meshview(
+    ctx: SaveContext,
+    output_folder: str,
+    split_fn: str,
+    pl: int,
+    cl: int,
+    prev_pl: int,
+    prev_cl: int,
+    section_intensities=None,
+):
+    """Write per-section MeshView JSONs for pixels and centroids."""
+    write_hemi_points_to_meshview(
+        ctx.pixel_points[prev_pl : pl + prev_pl]
+        if ctx.pixel_points is not None
+        else None,
+        ctx.labeled_points[prev_pl : pl + prev_pl]
+        if ctx.labeled_points is not None
+        else None,
+        ctx.points_hemi_labels[prev_pl : pl + prev_pl]
+        if ctx.points_hemi_labels is not None
+        else None,
+        f"{output_folder}/per_section_meshview/{ctx.prepend}{split_fn}_pixels.json",
+        ctx.atlas_labels,
+        section_intensities,
+        colormap=ctx.colormap,
+    )
+    if ctx.centroids is not None:
+        write_hemi_points_to_meshview(
+            ctx.centroids[prev_cl : cl + prev_cl],
+            ctx.labeled_points_centroids[prev_cl : cl + prev_cl],
+            ctx.centroids_hemi_labels[prev_cl : cl + prev_cl],
+            f"{output_folder}/per_section_meshview/{ctx.prepend}{split_fn}_centroids.json",
+            ctx.atlas_labels,
+            colormap=ctx.colormap,
+        )
+
+
+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.pixel_points,
+        ctx.labeled_points,
+        ctx.points_hemi_labels,
+        f"{output_folder}/whole_series_meshview/{ctx.prepend}pixels_meshview.json",
+        ctx.atlas_labels,
+        ctx.point_intensities,
+        colormap=ctx.colormap,
+    )
+    if ctx.centroids is not None:
+        write_hemi_points_to_meshview(
+            ctx.centroids,
+            ctx.labeled_points_centroids,
+            ctx.centroids_hemi_labels,
+            f"{output_folder}/whole_series_meshview/{ctx.prepend}objects_meshview.json",
+            ctx.atlas_labels,
+            colormap=ctx.colormap,
+        )