ngio 0.5.0b6__py3-none-any.whl → 0.5.1__py3-none-any.whl

ngio/io_pipes/_match_shape.py

@@ -1,4 +1,4 @@
-import warnings
+import logging
 from collections.abc import Sequence
 from enum import Enum
 
@@ -7,6 +7,8 @@ import numpy as np
 
 from ngio.utils import NgioValueError
 
+logger = logging.getLogger(f"ngio:{__name__}")
+
 
 class Action(str, Enum):
     NONE = "none"
@@ -29,10 +31,9 @@ def _compute_pad_widths(
             pad_def.append((before, after))
         else:
             pad_def.append((0, 0))
-    warnings.warn(
+    logger.warning(
         f"Images have a different shape ({array_shape} vs {target_shape}). "
-        f"Resolving by padding: {pad_def}",
-        stacklevel=2,
+        f"Resolving by padding: {pad_def}"
     )
     return tuple(pad_def)
 
@@ -76,10 +77,9 @@ def _compute_trim_slices(
         else:
             slices.append(slice(0, s))
 
-    warnings.warn(
+    logger.warning(
         f"Images have a different shape ({array_shape} vs {target_shape}). "
-        f"Resolving by trimming: {slices}",
-        stacklevel=2,
+        f"Resolving by trimming: {slices}"
     )
     return tuple(slices)
 
@@ -118,10 +118,9 @@ def _compute_rescaling_shape(
             rescaling_shape.append(s)
             factor.append(1.0)
 
-    warnings.warn(
+    logger.warning(
         f"Images have a different shape ({array_shape} vs {target_shape}). "
-        f"Resolving by scaling with factors {factor}.",
-        stacklevel=2,
+        f"Resolving by scaling with factors {factor}."
     )
     return tuple(rescaling_shape)
 
@@ -266,14 +265,11 @@ def numpy_match_shape(
         reference_axes (Sequence[str]): The axes names of the reference shape.
         tolerance (int): The maximum number of pixels by which dimensions
             can differ when matching shapes.
-        allow_broadcast (bool): If True, allow broadcasting new dimensions to
-            match the reference shape. If False, single-dimension axes will
-            be left as is.
         pad_mode (str): The mode to use for padding. See numpy.pad for options.
         pad_values (int | float): The constant value to use for padding if
             pad_mode is 'constant'.
         allow_rescaling (bool): If True, when the array differs more than the
-            tolerance, it will be rescalingd to the reference shape. If False,
+            tolerance, it will be rescaled to the reference shape. If False,
             an error will be raised.
     """
     _check_axes(

ngio/io_pipes/_ops_slices.py

@@ -1,7 +1,7 @@
+import logging
 import math
 from collections.abc import Mapping, Sequence
 from typing import TypeAlias, assert_never
-from warnings import warn
 
 import dask.array as da
 import numpy as np
@@ -13,6 +13,9 @@ from ngio.io_pipes._ops_slices_utils import compute_slice_chunks
 from ngio.ome_zarr_meta.ngio_specs import Axis
 from ngio.utils import NgioValueError
 
+logger = logging.getLogger(f"ngio:{__name__}")
+
+
 SlicingInputType: TypeAlias = slice | Sequence[int] | int | None
 SlicingType: TypeAlias = slice | list[int] | int
 
@@ -141,12 +144,11 @@ def _check_list_in_slicing_tuple(
     # Complex case, we have exactly one tuple in the slicing tuple
     ax, first_tuple = list_in_slice[0]
     if len(first_tuple) > 100:
-        warn(
+        logger.warning(
             "Performance warning: "
             "Non-contiguous slicing with a tuple/list with more than 100 elements is "
             "not natively supported by zarr. This is implemented by Ngio by performing "
-            "multiple reads and stacking the result.",
-            stacklevel=2,
+            "multiple reads and stacking the result."
         )
     return ax, first_tuple
 

ngio/io_pipes/_ops_slices_utils.py

@@ -1,10 +1,13 @@
-import warnings
+import logging
 from collections.abc import Iterable, Iterator
 from itertools import product
 from typing import TypeAlias, TypeVar
 
 from ngio.utils import NgioValueError
 
+logger = logging.getLogger(f"ngio:{__name__}")
+
+
 T = TypeVar("T")
 
 ##############################################################
@@ -86,10 +89,9 @@ def check_if_regions_overlap(slices: Iterable[tuple[SlicingType, ...]]) -> bool:
             return True
 
         if it == 10_000:
-            warnings.warn(
+            logger.warning(
                 "Performance Warning check_for_overlaps is O(n^2) and may be slow for "
-                "large numbers of regions.",
-                stacklevel=2,
+                "large numbers of regions."
             )
     return False
 
@@ -191,9 +193,8 @@ def check_if_chunks_overlap(
         if si & sj:
             return True
         if it == 10_000:
-            warnings.warn(
+            logger.warning(
                 "Performance Warning check_for_chunks_overlaps is O(n^2) and may be "
-                "slow for large numbers of regions.",
-                stacklevel=2,
+                "slow for large numbers of regions."
             )
     return False

ngio/ome_zarr_meta/_meta_handlers.py

@@ -176,8 +176,6 @@ def get_ngio_image_meta(
     group_handler: ZarrGroupHandler,
     version: str | None = None,
     axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = True,
 ) -> NgioImageMeta:
     """Retrieve the NGIO image metadata from the Zarr group.
 
@@ -185,19 +183,16 @@ def get_ngio_image_meta(
         group_handler (ZarrGroupHandler): The Zarr group handler.
         version (str | None): Optional NGFF version to use for decoding.
         axes_setup (AxesSetup | None): Optional axes setup for validation.
-        allow_non_canonical_axes (bool): Whether to allow non-canonical axes.
-        strict_canonical_order (bool): Whether to enforce strict canonical order.
 
     Returns:
         NgioImageMeta: The NGIO image metadata.
     """
+    # axes_setup = axes_setup or AxesSetup(x="XX")
     return get_ngio_meta(
         group_handler=group_handler,
         meta_type=NgioImageMeta,
         version=version,
         axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
     )
 
 
@@ -224,15 +219,10 @@ class ImageMetaHandler:
         group_handler: ZarrGroupHandler,
         version: str | None = None,
         axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
     ):
         self._group_handler = group_handler
         self._version = version
         self._axes_setup = axes_setup
-        self._allow_non_canonical_axes = allow_non_canonical_axes
-        self._strict_canonical_order = strict_canonical_order
-
         # Validate metadata
         meta = self.get_meta()
         # Store the resolved version
@@ -244,8 +234,6 @@ class ImageMetaHandler:
             group_handler=self._group_handler,
             version=self._version,
             axes_setup=self._axes_setup,
-            allow_non_canonical_axes=self._allow_non_canonical_axes,
-            strict_canonical_order=self._strict_canonical_order,
         )
 
     def update_meta(self, ngio_meta: NgioImageMeta) -> None:
@@ -260,8 +248,6 @@ def get_ngio_label_meta(
     group_handler: ZarrGroupHandler,
     version: str | None = None,
     axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = True,
 ) -> NgioLabelMeta:
     """Retrieve the NGIO label metadata from the Zarr group.
 
@@ -269,8 +255,6 @@ def get_ngio_label_meta(
         group_handler (ZarrGroupHandler): The Zarr group handler.
         version (str | None): Optional NGFF version to use for decoding.
         axes_setup (AxesSetup | None): Optional axes setup for validation.
-        allow_non_canonical_axes (bool): Whether to allow non-canonical axes.
-        strict_canonical_order (bool): Whether to enforce strict canonical order.
 
     Returns:
         NgioLabelMeta: The NGIO label metadata.
@@ -280,8 +264,6 @@ def get_ngio_label_meta(
         meta_type=NgioLabelMeta,
         version=version,
         axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
     )
 
 
@@ -306,16 +288,12 @@ class LabelMetaHandler:
     def __init__(
         self,
         group_handler: ZarrGroupHandler,
-        version: str | None = None,
         axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
+        version: str | None = None,
     ):
         self._group_handler = group_handler
         self._version = version
         self._axes_setup = axes_setup
-        self._allow_non_canonical_axes = allow_non_canonical_axes
-        self._strict_canonical_order = strict_canonical_order
 
         # Validate metadata
         meta = self.get_meta()
@@ -328,8 +306,6 @@ class LabelMetaHandler:
             group_handler=self._group_handler,
             version=self._version,
             axes_setup=self._axes_setup,
-            allow_non_canonical_axes=self._allow_non_canonical_axes,
-            strict_canonical_order=self._strict_canonical_order,
         )
 
     def update_meta(self, ngio_meta: NgioLabelMeta) -> None:

ngio/ome_zarr_meta/ngio_specs/__init__.py

@@ -15,6 +15,7 @@ from ngio.ome_zarr_meta.ngio_specs._axes import (
     DefaultTimeUnit,
     SpaceUnits,
     TimeUnits,
+    build_axes_handler,
     build_canonical_axes_handler,
     canonical_axes_order,
     canonical_label_axes_order,
@@ -69,6 +70,7 @@ __all__ = [
     "PixelSize",
     "SpaceUnits",
     "TimeUnits",
+    "build_axes_handler",
     "build_canonical_axes_handler",
     "canonical_axes_order",
     "canonical_label_axes_order",

ngio/ome_zarr_meta/ngio_specs/_axes.py

@@ -4,7 +4,7 @@ from collections.abc import Sequence
 from enum import Enum
 from typing import Literal, TypeAlias, TypeVar
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 
 from ngio.utils import NgioValidationError, NgioValueError
 
@@ -153,9 +153,51 @@ class AxesSetup(BaseModel):
     c: str = "c"
     t: str = "t"
     others: list[str] = Field(default_factory=list)
+    allow_non_canonical_axes: bool = False
+    strict_canonical_order: bool = False
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
+    @model_validator(mode="after")
+    def _validate_axes_values(self) -> "AxesSetup":
+        """Validate the axes values."""
+        canonical = {"x", "y", "z", "c", "t"}
+        axes = {"x": self.x, "y": self.y, "z": self.z, "c": self.c, "t": self.t}
+
+        for axis_name, axis_value in axes.items():
+            reserved = canonical - {axis_name}
+            if axis_value in reserved:
+                raise NgioValueError(
+                    f"The {axis_name} axis cannot be called: '{axis_value}'. "
+                    f"{axis_value} is reserved. If you want to set a non canonical "
+                    "axis order, please set the 'strict_canonical_order'to False."
+                )
+        return self
+
+    @classmethod
+    def from_ordered_list(
+        cls, axes_names: Sequence[str], canonical_order: Sequence[str]
+    ):
+        """Create an AxesSetup from an ordered list of axes names."""
+        # Make sure to only keep as many default axes as provided in axes_names
+        if len(axes_names) > len(canonical_order):
+            raise NgioValueError(
+                f"Cannot create AxesSetup from axes names {axes_names} "
+                f"and canonical order {canonical_order}. "
+                "The number of axes names cannot be greater than the "
+                "number of canonical axes."
+            )
+        canonical_order = list(canonical_order)
+        chanonical_axes = canonical_axes_order()
+        axes_mapping = {}
+        for ax in reversed(axes_names):
+            c_ax = canonical_order.pop()
+            if ax in chanonical_axes:
+                axes_mapping[ax] = ax
+            else:
+                axes_mapping[c_ax] = ax
+        return cls(**axes_mapping)
+
     def canonical_map(self) -> dict[str, str]:
         """Get the canonical map of axes."""
         return {
@@ -197,9 +239,9 @@ def _check_unique_names(axes: Sequence[Axis]):
         )
 
 
-def _check_non_canonical_axes(axes_setup: AxesSetup, allow_non_canonical_axes: bool):
+def _check_non_canonical_axes(axes_setup: AxesSetup):
     """Check if all axes are known."""
-    if not allow_non_canonical_axes and len(axes_setup.others) > 0:
+    if not axes_setup.allow_non_canonical_axes and len(axes_setup.others) > 0:
         raise NgioValidationError(
             f"Unknown axes {axes_setup.others}. Please set "
             "`allow_non_canonical_axes=True` to ignore them"
@@ -219,11 +261,9 @@ def _check_axes_validity(axes: Sequence[Axis], axes_setup: AxesSetup):
             )
 
 
-def _check_canonical_order(
-    axes: Sequence[Axis], axes_setup: AxesSetup, strict_canonical_order: bool
-):
+def _check_canonical_order(axes: Sequence[Axis], axes_setup: AxesSetup):
     """Check if the axes are in the canonical order."""
-    if not strict_canonical_order:
+    if not axes_setup.strict_canonical_order:
         return
     _names = [ax.name for ax in axes]
     _canonical_order = []
@@ -242,24 +282,18 @@ def _check_canonical_order(
 def validate_axes(
     axes: Sequence[Axis],
     axes_setup: AxesSetup,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = False,
 ) -> None:
     """Validate the axes."""
-    if allow_non_canonical_axes and strict_canonical_order:
-        raise NgioValidationError(
+    if axes_setup.allow_non_canonical_axes and axes_setup.strict_canonical_order:
+        raise NgioValueError(
             "`allow_non_canonical_axes` and"
             "`strict_canonical_order` cannot be true at the same time."
             "If non canonical axes are allowed, the order cannot be checked."
         )
     _check_unique_names(axes=axes)
-    _check_non_canonical_axes(
-        axes_setup=axes_setup, allow_non_canonical_axes=allow_non_canonical_axes
-    )
+    _check_non_canonical_axes(axes_setup=axes_setup)
     _check_axes_validity(axes=axes, axes_setup=axes_setup)
-    _check_canonical_order(
-        axes=axes, axes_setup=axes_setup, strict_canonical_order=strict_canonical_order
-    )
+    _check_canonical_order(axes=axes, axes_setup=axes_setup)
 
 
 class AxesHandler:
@@ -278,29 +312,22 @@ class AxesHandler:
         axes: Sequence[Axis],
         # user defined args
         axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = False,
     ):
         """Create a new AxesMapper object.
 
         Args:
             axes (list[Axis]): The axes on disk.
             axes_setup (AxesSetup, optional): The axis setup. Defaults to None.
-            allow_non_canonical_axes (bool, optional): Allow non canonical axes.
-            strict_canonical_order (bool, optional): Check if the axes are in the
-                canonical order. Defaults to False.
         """
         axes_setup = axes_setup if axes_setup is not None else AxesSetup()
 
         validate_axes(
             axes=axes,
             axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
         )
 
-        self._allow_non_canonical_axes = allow_non_canonical_axes
-        self._strict_canonical_order = strict_canonical_order
+        self._allow_non_canonical_axes = axes_setup.allow_non_canonical_axes
+        self._strict_canonical_order = axes_setup.strict_canonical_order
 
         self._canonical_order = canonical_axes_order()
 
@@ -422,8 +449,48 @@ class AxesHandler:
         return AxesHandler(
             axes=new_axes,
             axes_setup=self.axes_setup,
-            allow_non_canonical_axes=self.allow_non_canonical_axes,
-            strict_canonical_order=self.strict_canonical_order,
+        )
+
+    def rename_axes(self, axes_names: Sequence[str]) -> "AxesHandler":
+        """Rename the axes.
+
+        Args:
+            axes_names (Sequence[str]): The new axes names.
+        """
+        if len(axes_names) != len(self.axes):
+            raise NgioValueError(
+                f"Cannot rename axes. "
+                f"Expected {len(self.axes)} axes, but got {len(axes_names)}."
+            )
+        new_axes = []
+        axes_setup = self.axes_setup
+        for ax, new_name in zip(self.axes, axes_names, strict=True):
+            if ax.name == new_name:
+                new_axes.append(ax)
+                continue
+            new_ax = Axis(name=new_name, axis_type=ax.axis_type, unit=ax.unit)
+            match ax.name:
+                case axes_setup.x:
+                    axes_setup = axes_setup.model_copy(update={"x": new_name})
+                case axes_setup.y:
+                    axes_setup = axes_setup.model_copy(update={"y": new_name})
+                case axes_setup.z:
+                    axes_setup = axes_setup.model_copy(update={"z": new_name})
+                case axes_setup.c:
+                    axes_setup = axes_setup.model_copy(update={"c": new_name})
+                case axes_setup.t:
+                    axes_setup = axes_setup.model_copy(update={"t": new_name})
+                case _:
+                    if ax.name in axes_setup.others:
+                        others = axes_setup.others.copy()
+                        others.remove(ax.name)
+                        others.append(new_name)
+                        axes_setup = axes_setup.model_copy(update={"others": others})
+            new_axes.append(new_ax)
+            # Update the axes setup
+        return AxesHandler(
+            axes=new_axes,
+            axes_setup=axes_setup,
         )
 
     def get_index(self, name: str) -> int | None:
@@ -465,14 +532,33 @@ class AxesHandler:
         self._axes = new_axes
 
 
+def _build_axes_list_from_names(
+    axes_names: Sequence[str],
+    axes_setup: AxesSetup,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
+) -> list[Axis]:
+    """Build a list of Axis objects from a list of axis names."""
+    axes = []
+    for name in axes_names:
+        c_name = axes_setup.get_canonical_name(name)
+        match c_name:
+            case "t":
+                axes.append(Axis(name=name, axis_type=AxisType.time, unit=time_unit))
+            case "c":
+                axes.append(Axis(name=name, axis_type=AxisType.channel))
+            case "z" | "y" | "x":
+                axes.append(Axis(name=name, axis_type=AxisType.space, unit=space_unit))
+            case _:
+                axes.append(Axis(name=name, axis_type=AxisType.space))
+    return axes
+
+
 def build_canonical_axes_handler(
     axes_names: Sequence[str],
-    space_units: SpaceUnits | str | None = DefaultSpaceUnit,
-    time_units: TimeUnits | str | None = DefaultTimeUnit,
-    # user defined args
-    axes_setup: AxesSetup | None = None,
-    allow_non_canonical_axes: bool = False,
-    strict_canonical_order: bool = False,
+    canonical_channel_order: Sequence[str] | None = None,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
 ) -> AxesHandler:
     """Create a new canonical axes mapper.
 
@@ -483,33 +569,50 @@ def build_canonical_axes_handler(
             - If an integer is provided, the axes are created from the last axis
               to the first
                 e.g. 3 -> ["z", "y", "x"]
-        space_units (SpaceUnits, optional): The space units. Defaults to None.
-        time_units (TimeUnits, optional): The time units. Defaults to None.
-        axes_setup (AxesSetup, optional): The axis setup. Defaults to None.
-        allow_non_canonical_axes (bool, optional): Allow non canonical axes.
-            Defaults to False.
-        strict_canonical_order (bool, optional): Check if the axes are in the
-            canonical order. Defaults to False.
-
+        canonical_channel_order (Sequence[str], optional): The canonical channel
+            order. Defaults to None, which uses the default order.
+        space_unit (SpaceUnits, optional): The space units. Defaults to None.
+        time_unit (TimeUnits, optional): The time units. Defaults to None.
     """
-    axes = []
-    for name in axes_names:
-        match name:
-            case "t":
-                axes.append(Axis(name=name, axis_type=AxisType.time, unit=time_units))
-            case "c":
-                axes.append(Axis(name=name, axis_type=AxisType.channel))
-            case "z" | "y" | "x":
-                axes.append(Axis(name=name, axis_type=AxisType.space, unit=space_units))
-            case _:
-                raise NgioValueError(
-                    f"Invalid axis name '{name}'. "
-                    "Only 't', 'c', 'z', 'y', 'x' are allowed."
-                )
+    if canonical_channel_order is None:
+        canonical_channel_order = canonical_axes_order()
+    axes_setup = AxesSetup.from_ordered_list(
+        axes_names=axes_names, canonical_order=canonical_channel_order
+    )
+    axes = _build_axes_list_from_names(
+        axes_names=axes_names,
+        axes_setup=axes_setup,
+        space_unit=space_unit,
+        time_unit=time_unit,
+    )
+    return AxesHandler(
+        axes=axes,
+        axes_setup=axes_setup,
+    )
+
 
+def build_axes_handler(
+    axes_names: Sequence[str],
+    axes_setup: AxesSetup | None = None,
+    space_unit: SpaceUnits | str | None = DefaultSpaceUnit,
+    time_unit: TimeUnits | str | None = DefaultTimeUnit,
+) -> AxesHandler:
+    """Create a new axes mapper.
+
+    Args:
+        axes_names (Sequence[str]): The axes names on disk.
+        axes_setup (AxesSetup, optional): The axis setup. Defaults to None.
+        space_unit (SpaceUnits, optional): The space units. Defaults to None.
+        time_unit (TimeUnits, optional): The time units. Defaults to None.
+    """
+    axes_setup = axes_setup if axes_setup is not None else AxesSetup()
+    axes = _build_axes_list_from_names(
+        axes_names=axes_names,
+        axes_setup=axes_setup,
+        space_unit=space_unit,
+        time_unit=time_unit,
+    )
     return AxesHandler(
         axes=axes,
         axes_setup=axes_setup,
-        allow_non_canonical_axes=allow_non_canonical_axes,
-        strict_canonical_order=strict_canonical_order,
     )