PyNutil 0.6.1__tar.gz → 0.6.2__tar.gz

{pynutil-0.6.1 → pynutil-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyNutil
-Version: 0.6.1
+Version: 0.6.2
 Summary: a package to quantify atlas registered brain data
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Neural-Systems-at-UIO/PyNutil

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/__init__.py

@@ -4,7 +4,9 @@ from .processing.adapters import read_alignment
 from .io.atlas_loader import load_custom_atlas
 from .image_series import Section, ImageSeries
 from .processing.pipeline.batch_processor import (
+    read_segmentation,
     read_segmentation_dir,
+    read_image,
     read_image_dir,
     seg_to_coords,
     image_to_coords,
@@ -24,7 +26,9 @@ __all__ = [
     "load_custom_atlas",
     "Section",
     "ImageSeries",
+    "read_segmentation",
     "read_segmentation_dir",
+    "read_image",
     "read_image_dir",
     "seg_to_coords",
     "image_to_coords",

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/io/file_operations.py

@@ -38,11 +38,6 @@ class SaveContext:
 
 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):
@@ -62,7 +57,7 @@ def save_analysis_output(ctx: SaveContext, output_folder: str):
     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}",
+            f"{output_folder}/{ctx.prepend}{report_name}",
             sep=";",
             na_rep="",
             index=False,
@@ -74,7 +69,7 @@ def save_analysis_output(ctx: SaveContext, output_folder: str):
         )
 
     if ctx.points is not None:
-        _save_whole_series_meshview(ctx, output_folder)
+        _save_meshview(ctx, output_folder)
 
     _save_settings_json(ctx, output_folder)
 
@@ -88,13 +83,13 @@ def _save_settings_json(ctx: SaveContext, output_folder: str) -> None:
         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."""
+def _save_meshview(ctx: SaveContext, output_folder: str):
+    """Write 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",
+        f"{output_folder}/{ctx.prepend}pixels_meshview.json",
         ctx.atlas_labels,
         ctx.point_values,
         colormap=ctx.colormap,
@@ -104,7 +99,7 @@ def _save_whole_series_meshview(ctx: SaveContext, output_folder: str):
             ctx.objects,
             ctx.object_labels,
             ctx.objects_hemi_labels,
-            f"{output_folder}/whole_series_meshview/{ctx.prepend}objects_meshview.json",
+            f"{output_folder}/{ctx.prepend}objects_meshview.json",
             ctx.atlas_labels,
             colormap=ctx.colormap,
         )
@@ -121,13 +116,20 @@ def save_analysis(
 ):
     """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.
+    Parameters
+    ----------
+    output_folder : str
+        Directory to write output files.
+    result : ExtractionResult
+        ExtractionResult from coordinate extraction.
+    atlas_labels : DataFrame or AtlasData
+        Atlas labels DataFrame (or AtlasData — ``.labels`` used).
+    label_df : DataFrame, optional
+        Whole-series quantification DataFrame.
+    colormap : str
+        Colormap for MeshView intensity output.
+    settings_dict : dict, optional
+        Optional dict written to pynutil_settings.json.
     """
     atlas_labels = resolve_atlas_labels(atlas_labels)
 
@@ -171,7 +173,7 @@ def save_analysis(
         remapped["idx"] = remapped["original_idx"]
         remapped = remapped.drop(columns=["original_idx"])
         remapped.to_csv(
-            f"{output_folder}/whole_series_report/counts.csv",
+            f"{output_folder}/counts.csv",
             sep=";",
             index=False,
         )

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/io/loaders.py

@@ -203,11 +203,15 @@ def read_seg_file(file: str) -> np.ndarray:
 def number_sections(filenames):
     """Extract section numbers from a list of filenames.
 
-    Args:
-        filenames (list): List of file paths.
+    Parameters
+    ----------
+    filenames : list
+        List of file paths.
 
-    Returns:
-        list: List of section numbers as integers.
+    Returns
+    -------
+    list
+        List of section numbers as integers.
     """
     filenames = [os.path.basename(filename) for filename in filenames]
     section_numbers = []

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/io/nifti_writer.py

@@ -17,11 +17,16 @@ def write_nifti(
 
     The header is written with both qform and sform set and units set to microns.
 
-    Args:
-        volume: 3D volume array. Saved as uint8.
-        voxel_size_um: Isotropic voxel size in microns.
-        output_path: Output path without extension; ".nii.gz" is appended.
-        origin_offsets_um: Optional XYZ translation offsets in microns.
+    Parameters
+    ----------
+    volume : ndarray
+        3D volume array. Saved as uint8.
+    voxel_size_um : float
+        Isotropic voxel size in microns.
+    output_path : str
+        Output path without extension; ".nii.gz" is appended.
+    origin_offsets_um : ndarray, optional
+        Optional XYZ translation offsets in microns.
     """
 
     if origin_offsets_um is None:

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/io/section_visualisation.py

@@ -23,16 +23,14 @@ def _build_color_lookup(
 ) -> Tuple[str, Union[np.ndarray, Tuple[np.ndarray, np.ndarray]], Tuple[int, int, int]]:
     """Build a fast color lookup for atlas IDs.
 
-    Returns:
-        (mode, lookup, default_colour)
-
-    mode:
-        - "direct": lookup is a (max_id+1, 3) uint8 LUT; index directly by atlas ID
-        - "sorted": lookup is (ids_sorted, rgb_sorted); use searchsorted
-
-    This keeps behaviour consistent with the previous implementation:
-    - atlas id 0 maps to black
-    - unmapped ids map to grey (default_colour)
+    Returns
+    -------
+    tuple
+        (mode, lookup, default_colour) where *mode* is ``"direct"`` if
+        lookup is a (max_id+1, 3) uint8 LUT indexed directly by atlas ID,
+        or ``"sorted"`` if lookup is (ids_sorted, rgb_sorted) for use with
+        searchsorted. Atlas ID 0 maps to black; unmapped IDs map to
+        *default_colour*.
     """
     if atlas_labels is None or len(atlas_labels) == 0:
         lut = np.empty((2, 3), dtype=np.uint8)

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/processing/adapters/base.py

@@ -154,11 +154,17 @@ class DeformationProvider(ABC):
     def apply(self, data: RegistrationData) -> RegistrationData:
         """Add deformation functions to all slices.
 
-        Args:
-            data: RegistrationData with basic anchoring.
-
-        Returns:
-            RegistrationData with deformation functions added.
+        Parameters
+        ----------
+        data : RegistrationData
+            Registration data whose slices contain linear atlas anchoring.
+            The provider augments each slice with inverse and forward
+            non-linear deformation functions.
+
+        Returns
+        -------
+        RegistrationData
+            With deformation functions added.
         """
         pass
 
@@ -177,10 +183,16 @@ class DamageProvider(ABC):
     def apply(self, data: RegistrationData) -> RegistrationData:
         """Add damage masks to all slices.
 
-        Args:
-            data: RegistrationData (may already have deformation).
-
-        Returns:
-            RegistrationData with damage masks added.
+        Parameters
+        ----------
+        data : RegistrationData
+            Registration data whose slices contain linear anchoring and may
+            also contain deformation functions. The provider augments each
+            slice with a damage/exclusion mask.
+
+        Returns
+        -------
+        RegistrationData
+            With damage masks added.
         """
         pass

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/processing/adapters/damage.py

@@ -22,13 +22,19 @@ from ...io.loaders import load_json_file
 def create_damage_mask(slice_info, section_grid, grid_spacing):
     """Create a binary damage mask from grid information in the given section.
 
-    Args:
-        slice_info: SliceInfo with anchoring and registration dimensions.
-        section_grid (dict): Dictionary with grid data (grid, gridx, gridy).
-        grid_spacing (int): Space between grid marks.
-
-    Returns:
-        ndarray: Binary mask with damaged areas marked as 0.
+    Parameters
+    ----------
+    slice_info : SliceInfo
+        SliceInfo with anchoring and registration dimensions.
+    section_grid : dict
+        Dictionary with grid data (grid, gridx, gridy).
+    grid_spacing : int
+        Space between grid marks.
+
+    Returns
+    -------
+    ndarray
+        Binary mask with damaged areas marked as 0.
     """
     width = slice_info.width
     height = slice_info.height
@@ -70,9 +76,11 @@ class QCAlignDamageProvider(DamageProvider):
     def __init__(self, path: Optional[str] = None):
         """Initialize provider.
 
-        Args:
-            path: Optional separate file with QCAlign damage grids.
-                  If None, uses grids from the anchoring file.
+        Parameters
+        ----------
+        path : str, optional
+            Optional separate file with QCAlign damage grids.
+            If None, uses grids from the anchoring file.
         """
         self.path = path
 

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/processing/adapters/deformation.py

@@ -40,9 +40,11 @@ class VisuAlignDeformationProvider(DeformationProvider):
     def __init__(self, path: Optional[str] = None):
         """Initialize provider.
 
-        Args:
-            path: Optional separate file with VisuAlign markers.
-                  If None, uses markers from the anchoring file.
+        Parameters
+        ----------
+        path : str, optional
+            Optional separate file with VisuAlign markers.
+            If None, uses markers from the anchoring file.
         """
         self.path = path
 
@@ -63,8 +65,10 @@ class VisuAlignDeformationProvider(DeformationProvider):
     ) -> Tuple[DeformationFunction, DeformationFunction]:
         """Create deformation functions from VisuAlign markers.
 
-        Returns:
-            Tuple of (inverse_deform, forward_deform) functions.
+        Returns
+        -------
+        tuple
+            (inverse_deform, forward_deform) functions.
             - inverse_deform: maps from deformed to original (transform_vec)
             - forward_deform: maps from original to deformed (forwardtransform_vec)
         """
@@ -135,9 +139,11 @@ class BrainGlobeDeformationProvider(DeformationProvider):
     def __init__(self, reg_dir: Optional[str] = None):
         """Initialize provider.
 
-        Args:
-            reg_dir: Directory containing deformation field TIFFs.
-                     If None, the directory is taken from SliceInfo metadata.
+        Parameters
+        ----------
+        reg_dir : str, optional
+            Directory containing deformation field TIFFs.
+            If None, the directory is taken from SliceInfo metadata.
         """
         self.reg_dir = reg_dir
 
@@ -146,9 +152,11 @@ class BrainGlobeDeformationProvider(DeformationProvider):
     ) -> Tuple[np.ndarray, np.ndarray]:
         """Load deformation field TIFFs from *reg_dir*.
 
-        Raises:
-            FileNotFoundError: If deformation field TIFFs are missing, which
-                should not happen for a valid brainglobe registration output.
+        Raises
+        ------
+        FileNotFoundError
+            If deformation field TIFFs are missing, which should not happen
+            for a valid brainglobe registration output.
         """
         f0_path = os.path.join(reg_dir, "deformation_field_0.tiff")
         f1_path = os.path.join(reg_dir, "deformation_field_1.tiff")

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/processing/adapters/registry.py

@@ -7,6 +7,7 @@ and damage providers.
 
 from __future__ import annotations
 
+import os
 from typing import Dict, Optional, Type
 
 from .base import (
@@ -60,39 +61,52 @@ def read_alignment(
     deformation_provider: Optional[DeformationProvider] = None,
     damage_provider: Optional[DamageProvider] = None,
 ) -> RegistrationData:
-    """Load registration data with composable pipeline.
+    """Load registration data for downstream PyNutil processing.
 
     This is the main entry point for loading registration data. It supports
     mixing and matching different components.
 
-    Args:
-        path: Path to the registration file.
-        loader_name: Explicit loader name, or None for auto-detection.
-        apply_deformation: Whether to apply deformation from the file.
-                          Set False to use only linear anchoring.
-        apply_damage: Whether to apply damage masks from the file.
-        deformation_provider: Custom deformation provider to use instead of
-                             the default (VisuAlign for QUINT files).
-        damage_provider: Custom damage provider to use instead of
-                        the default (QCAlign for QUINT files).
-
-    Returns:
-        RegistrationData with all components applied.
-
-    Examples:
-        # Standard QUINT workflow
-        data = read_alignment("alignment.json")
-
-        # Linear only (no VisuAlign deformation)
-        data = read_alignment("alignment.json", apply_deformation=False)
-
-        # Separate anchoring and damage files
-        from .damage import QCAlignDamageProvider
-        data = read_alignment(
-            "quicknii.json",
-            damage_provider=QCAlignDamageProvider("qcalign_output.json")
-        )
+    Parameters
+    ----------
+    path
+        Path to a registration file produced by a supported workflow such as
+        QuickNII, VisuAlign, or BrainGlobe registration.
+    loader_name
+        Explicit loader name to use. If ``None``, PyNutil attempts to detect
+        the appropriate loader automatically from the file.
+    apply_deformation
+        If ``True``, apply non-linear deformation when supported by the input
+        registration source. Set to ``False`` to keep only the linear
+        anchoring transform.
+    apply_damage
+        If ``True``, load and attach damage masks when available.
+    deformation_provider
+        Optional custom deformation provider to use instead of the default
+        provider selected for the detected registration type.
+    damage_provider
+        Optional custom damage provider to use instead of the default QCAlign
+        integration.
+
+    Returns
+    -------
+    RegistrationData
+        Registration metadata and per-section transforms used by the
+        segmentation, intensity, and coordinate pipelines.
+
+    Examples
+    --------
+    Load a standard QUINT alignment file:
+
+    >>> registration = read_alignment("alignment.json")
+
+    Load BrainGlobe registration output in the same way:
+
+    >>> registration = read_alignment("brainglobe-registration.json")
     """
+    # Accept both str and os.PathLike (e.g. pathlib.Path); loaders below
+    # rely on string operations like ``path.endswith(...)``.
+    path = os.fspath(path)
+
     # 1. Load anchoring
     if loader_name:
         loader = AnchoringLoaderRegistry.get(loader_name)

{pynutil-0.6.1 → pynutil-0.6.2}/PyNutil/processing/adapters/segmentation.py

@@ -102,11 +102,16 @@ class SegmentationAdapter(ABC):
     ) -> np.ndarray:
         """Create a binary mask from the segmentation.
 
-        Args:
-            segmentation: The loaded segmentation image.
-            pixel_id: Optional pixel color to match (for color-based formats).
+        Parameters
+        ----------
+        segmentation : ndarray
+            The loaded segmentation image.
+        pixel_id : list of int, optional
+            Pixel color to match (for color-based formats).
 
-        Returns:
+        Returns
+        -------
+        ndarray
             Boolean 2D array where True indicates foreground.
         """
         pass
@@ -120,13 +125,19 @@ class SegmentationAdapter(ABC):
     ) -> List[ObjectInfo]:
         """Extract individual objects from the segmentation.
 
-        Args:
-            segmentation: The loaded segmentation image.
-            binary_mask: The binary mask from create_binary_mask().
-            min_area: Minimum object area threshold.
+        Parameters
+        ----------
+        segmentation : ndarray
+            The loaded segmentation image.
+        binary_mask : ndarray
+            The binary mask from create_binary_mask().
+        min_area : int, optional
+            Minimum object area threshold.
 
-        Returns:
-            List of ObjectInfo for each detected object.
+        Returns
+        -------
+        list of ObjectInfo
+            For each detected object.
         """
         pass
 
@@ -136,11 +147,15 @@ class SegmentationAdapter(ABC):
         Override this method for formats that use color-coded pixels.
         Default implementation returns None (not applicable).
 
-        Args:
-            segmentation: The loaded segmentation image.
+        Parameters
+        ----------
+        segmentation : ndarray
+            The loaded segmentation image.
 
-        Returns:
-            List of [R, G, B] values or None if not applicable.
+        Returns
+        -------
+        list of int or None
+            [R, G, B] values or None if not applicable.
         """
         return None