ngio 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

ngio/ome_zarr_meta/ngio_specs/_dataset.py

@@ -1,87 +1,51 @@
 """Fractal internal module for dataset metadata handling."""
 
-from collections.abc import Collection
+from collections.abc import Sequence
 
 from ngio.ome_zarr_meta.ngio_specs._axes import (
-    AxesMapper,
-    AxesSetup,
-    Axis,
-    AxisType,
-    DefaultSpaceUnit,
-    DefaultTimeUnit,
-    SpaceUnits,
-    TimeUnits,
+    AxesHandler,
 )
 from ngio.ome_zarr_meta.ngio_specs._pixel_size import PixelSize
 from ngio.utils import NgioValidationError
 
 
 class Dataset:
-    """Model for a dataset in the multiscale.
-
-    To initialize the Dataset object, the path, the axes, scale, and translation list
-    can be provided with on_disk order.
-    """
+    """Model for a dataset in the multiscale."""
 
     def __init__(
         self,
         *,
         # args coming from ngff specs
         path: str,
-        on_disk_axes: Collection[Axis],
-        on_disk_scale: Collection[float],
-        on_disk_translation: Collection[float] | None = None,
-        # user defined args
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = False,
+        axes_handler: AxesHandler,
+        scale: Sequence[float],
+        translation: Sequence[float] | None = None,
     ):
         """Initialize the Dataset object.
 
         Args:
             path (str): The path of the dataset.
-            on_disk_axes (list[Axis]): The list of axes in the multiscale.
-            on_disk_scale (list[float]): The list of scale transformation.
+            axes_handler (AxesHandler): The axes handler object.
+            scale (list[float]): The list of scale transformation.
                 The scale transformation must have the same length as the axes.
-            on_disk_translation (list[float] | None): The list of translation.
-            axes_setup (AxesSetup): The axes setup object
-            allow_non_canonical_axes (bool): Allow non-canonical axes.
-            strict_canonical_order (bool): Strict canonical order.
+            translation (list[float] | None): The list of translation.
+                The translation must have the same length as the axes.
         """
         self._path = path
-        self._axes_mapper = AxesMapper(
-            on_disk_axes=on_disk_axes,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )
+        self._axes_handler = axes_handler
 
-        if len(on_disk_scale) != len(on_disk_axes):
+        if len(scale) != len(axes_handler.axes):
             raise NgioValidationError(
                 "The length of the scale transformation must be the same as the axes."
             )
-        self._on_disk_scale = list(on_disk_scale)
+        self._scale = list(scale)
 
-        on_disk_translation = on_disk_translation or [0.0] * len(on_disk_axes)
-        if len(on_disk_translation) != len(on_disk_axes):
+        translation = translation or [0.0] * len(axes_handler.axes)
+        if len(translation) != len(axes_handler.axes):
             raise NgioValidationError(
                 "The length of the translation must be the same as the axes."
             )
-        self._on_disk_translation = list(on_disk_translation)
-
-    def get_scale(self, axis_name: str) -> float:
-        """Return the scale for a given axis."""
-        idx = self._axes_mapper.get_index(axis_name)
-        if idx is None:
-            return 1.0
-        return self._on_disk_scale[idx]
-
-    def get_translation(self, axis_name: str) -> float:
-        """Return the translation for a given axis."""
-        idx = self._axes_mapper.get_index(axis_name)
-        if idx is None:
-            return 0.0
-        return self._on_disk_translation[idx]
+        self._translation = list(translation)
 
     @property
     def path(self) -> str:
@@ -89,84 +53,46 @@ class Dataset:
         return self._path
 
     @property
-    def space_unit(self) -> str | None:
-        """Return the space unit for a given axis."""
-        x_axis = self._axes_mapper.get_axis("x")
-        y_axis = self._axes_mapper.get_axis("y")
-
-        if x_axis is None or y_axis is None:
-            raise NgioValidationError(
-                "The dataset must have x and y axes to determine the space unit."
-            )
-
-        if x_axis.unit == y_axis.unit:
-            return x_axis.unit
-        else:
-            raise NgioValidationError(
-                "Inconsistent space units. "
-                f"x={x_axis.unit} and y={y_axis.unit} should have the same unit."
-            )
-
-    @property
-    def time_unit(self) -> str | None:
-        """Return the time unit for a given axis."""
-        t_axis = self._axes_mapper.get_axis("t")
-        if t_axis is None:
-            return None
-        return t_axis.unit
+    def axes_handler(self) -> AxesHandler:
+        """Return the axes handler object."""
+        return self._axes_handler
 
     @property
     def pixel_size(self) -> PixelSize:
         """Return the pixel size for the dataset."""
         return PixelSize(
-            x=self.get_scale("x"),
-            y=self.get_scale("y"),
-            z=self.get_scale("z"),
-            t=self.get_scale("t"),
-            space_unit=self.space_unit,  # type: ignore
-            time_unit=self.time_unit,  # type: ignore
+            x=self.get_scale("x", default=1.0),
+            y=self.get_scale("y", default=1.0),
+            z=self.get_scale("z", default=1.0),
+            t=self.get_scale("t", default=1.0),
+            space_unit=self.axes_handler.space_unit,
+            time_unit=self.axes_handler.time_unit,
         )
 
     @property
-    def axes_mapper(self) -> AxesMapper:
-        """Return the axes mapper object."""
-        return self._axes_mapper
+    def scale(self) -> tuple[float, ...]:
+        """Return the scale transformation as a tuple."""
+        return tuple(self._scale)
 
-    def to_units(
-        self,
-        *,
-        space_unit: SpaceUnits = DefaultSpaceUnit,
-        time_unit: TimeUnits = DefaultTimeUnit,
-    ) -> "Dataset":
-        """Convert the pixel size to the given units.
+    @property
+    def translation(self) -> tuple[float, ...]:
+        """Return the translation as a tuple."""
+        return tuple(self._translation)
 
-        Args:
-            space_unit(str): The space unit to convert to.
-            time_unit(str): The time unit to convert to.
-        """
-        new_axes = []
-        for ax in self.axes_mapper.on_disk_axes:
-            if ax.axis_type == AxisType.space:
-                new_ax = Axis(
-                    on_disk_name=ax.on_disk_name,
-                    axis_type=ax.axis_type,
-                    unit=space_unit,
-                )
-                new_axes.append(new_ax)
-            elif ax.axis_type == AxisType.time:
-                new_ax = Axis(
-                    on_disk_name=ax.on_disk_name, axis_type=ax.axis_type, unit=time_unit
-                )
-                new_axes.append(new_ax)
-            else:
-                new_axes.append(ax)
+    def get_scale(self, axis_name: str, default: float | None = None) -> float:
+        """Return the scale for a given axis."""
+        idx = self.axes_handler.get_index(axis_name)
+        if idx is None:
+            if default is not None:
+                return default
+            raise ValueError(f"Axis {axis_name} not found in axes {self.axes_handler}.")
+        return self._scale[idx]
 
-        return Dataset(
-            path=self.path,
-            on_disk_axes=new_axes,
-            on_disk_scale=self._on_disk_scale,
-            on_disk_translation=self._on_disk_translation,
-            axes_setup=self.axes_mapper.axes_setup,
-            allow_non_canonical_axes=self.axes_mapper.allow_non_canonical_axes,
-            strict_canonical_order=self.axes_mapper.strict_canonical_order,
-        )
+    def get_translation(self, axis_name: str, default: float | None = None) -> float:
+        """Return the translation for a given axis."""
+        idx = self.axes_handler.get_index(axis_name)
+        if idx is None:
+            if default is not None:
+                return default
+            raise ValueError(f"Axis {axis_name} not found in axes {self.axes_handler}.")
+        return self._translation[idx]

ngio/ome_zarr_meta/ngio_specs/_ngio_hcs.py

@@ -21,21 +21,12 @@ from ngio.utils import NgioValueError, ngio_logger
 
 def path_in_well_validation(path: str) -> str:
     """Validate the path in the well."""
-    if path.find("_") != -1:
-        # Remove underscores from the path
-        # This is a custom serialization step
-        old_value = path
-        path = path.replace("_", "")
-        ngio_logger.warning(
-            f"Underscores in well-paths are not allowed. "
-            f"Path '{old_value}' was changed to '{path}'"
-            f" to comply with the specification."
-        )
     # Check if the value contains only alphanumeric characters
     if not path.isalnum():
-        raise NgioValueError(
+        ngio_logger.warning(
             f"Path '{path}' contains non-alphanumeric characters. "
-            f"Only alphanumeric characters are allowed."
+            "This may cause issues with some tools. "
+            "Consider using only alphanumeric characters in the path."
         )
     return path
 
@@ -60,11 +51,11 @@ class CustomWellImage(WellImage04):
 
 
 class CustomWellMeta(WellMeta04):
-    images: list[CustomWellImage]  # type: ignore[valid-type]
+    images: list[CustomWellImage]  # type: ignore (override of WellMeta04.images)
 
 
 class CustomWellAttrs(WellAttrs04):
-    well: CustomWellMeta  # type: ignore[valid-type]
+    well: CustomWellMeta  # type: ignore (override of WellAttrs04.well)
 
 
 class NgioWellMeta(CustomWellAttrs):
@@ -540,7 +531,7 @@ class NgioPlateMeta(HCSAttrs):
             acquisitions = None
 
         if version is None:
-            version = self.plate.version  # type: ignore[assignment]
+            version = self.plate.version  # type: ignore (version is NgffVersions or None)
 
         return NgioPlateMeta(
             plate=Plate(

ngio/ome_zarr_meta/ngio_specs/_ngio_image.py

@@ -6,7 +6,7 @@ But they can be built from the OME standard metadata, and the
 can be converted to the OME standard.
 """
 
-from collections.abc import Collection
+from collections.abc import Sequence
 from typing import Any, Literal, TypeVar
 
 import numpy as np
@@ -17,9 +17,9 @@ from ngio.ome_zarr_meta.ngio_specs._axes import (
     DefaultTimeUnit,
     SpaceUnits,
     TimeUnits,
-    canonical_axes,
+    build_canonical_axes_handler,
 )
-from ngio.ome_zarr_meta.ngio_specs._channels import Channel, ChannelsMeta
+from ngio.ome_zarr_meta.ngio_specs._channels import ChannelsMeta
 from ngio.ome_zarr_meta.ngio_specs._dataset import Dataset
 from ngio.ome_zarr_meta.ngio_specs._pixel_size import PixelSize
 from ngio.utils import NgioValidationError, NgioValueError
@@ -55,38 +55,39 @@ class AbstractNgioImageMeta:
             raise NgioValidationError("At least one dataset must be provided.")
 
         self._datasets = datasets
-        self._axes_mapper = datasets[0].axes_mapper
+        self._axes_handler = datasets[0].axes_handler
 
     def __repr__(self):
         class_name = type(self).__name__
         paths = [dataset.path for dataset in self.datasets]
-        on_disk_axes = self.axes_mapper.on_disk_axes_names
-        return f"{class_name}(name={self.name}, datasets={paths}, axes={on_disk_axes})"
+        axes = self.axes_handler.axes_names
+        return f"{class_name}(name={self.name}, datasets={paths}, axes={axes})"
 
     @classmethod
     def default_init(
         cls,
-        levels: int | Collection[str],
-        axes_names: Collection[str],
+        levels: int | Sequence[str],
+        axes_names: Sequence[str],
         pixel_size: PixelSize,
-        scaling_factors: Collection[float] | None = None,
+        scaling_factors: Sequence[float] | None = None,
         name: str | None = None,
         version: NgffVersions = DefaultNgffVersion,
     ):
         """Initialize the ImageMeta object."""
-        axes = canonical_axes(
+        axes_handler = build_canonical_axes_handler(
             axes_names,
-            space_units=pixel_size.space_unit,  # type: ignore[arg-type]
-            time_units=pixel_size.time_unit,  # type: ignore[arg-type]
+            space_units=pixel_size.space_unit,
+            time_units=pixel_size.time_unit,
         )
 
         px_size_dict = pixel_size.as_dict()
-        scale = [px_size_dict.get(ax.on_disk_name, 1.0) for ax in axes]
-        translation = [0.0] * len(scale)
+        scale = [px_size_dict.get(name, 1.0) for name in axes_handler.axes_names]
 
         if scaling_factors is None:
             _default = {"x": 2.0, "y": 2.0}
-            scaling_factors = [_default.get(ax.on_disk_name, 1.0) for ax in axes]
+            scaling_factors = [
+                _default.get(name, 1.0) for name in axes_handler.axes_names
+            ]
 
         if isinstance(levels, int):
             levels = [str(i) for i in range(levels)]
@@ -95,11 +96,9 @@ class AbstractNgioImageMeta:
         for level in levels:
             dataset = Dataset(
                 path=level,
-                on_disk_axes=axes,
-                on_disk_scale=scale,
-                on_disk_translation=translation,
-                allow_non_canonical_axes=False,
-                strict_canonical_order=True,
+                axes_handler=axes_handler,
+                scale=scale,
+                translation=None,
             )
             datasets.append(dataset)
             scale = [s * f for s, f in zip(scale, scaling_factors, strict=True)]
@@ -122,9 +121,18 @@ class AbstractNgioImageMeta:
             space_unit(str): The space unit to convert to.
             time_unit(str): The time unit to convert to.
         """
+        new_axes_handler = self.axes_handler.to_units(
+            space_unit=space_unit,
+            time_unit=time_unit,
+        )
         new_datasets = []
         for dataset in self.datasets:
-            new_dataset = dataset.to_units(space_unit=space_unit, time_unit=time_unit)
+            new_dataset = Dataset(
+                path=dataset.path,
+                axes_handler=new_axes_handler,
+                scale=dataset.scale,
+                translation=dataset.translation,
+            )
             new_datasets.append(new_dataset)
 
         return type(self)(
@@ -136,7 +144,7 @@ class AbstractNgioImageMeta:
     @property
     def version(self) -> NgffVersions:
         """Version of the OME-NFF metadata used to build the object."""
-        return self._version  # type: ignore[return-value]
+        return self._version  # type: ignore (version is a Literal type)
 
     @property
     def name(self) -> str | None:
@@ -149,9 +157,9 @@ class AbstractNgioImageMeta:
         return self._datasets
 
     @property
-    def axes_mapper(self):
+    def axes_handler(self):
         """Return the axes mapper."""
-        return self._axes_mapper
+        return self._axes_handler
 
     @property
     def levels(self) -> int:
@@ -166,12 +174,12 @@ class AbstractNgioImageMeta:
     @property
     def space_unit(self) -> str | None:
         """Get the space unit of the pixel size."""
-        return self.datasets[0].pixel_size.space_unit
+        return self.axes_handler.space_unit
 
     @property
     def time_unit(self) -> str | None:
         """Get the time unit of the pixel size."""
-        return self.datasets[0].pixel_size.time_unit
+        return self.axes_handler.time_unit
 
     def _get_dataset_by_path(self, path: str) -> Dataset:
         """Get a dataset by its path."""
@@ -321,11 +329,11 @@ class AbstractNgioImageMeta:
     def scaling_factor(self, path: str | None = None) -> list[float]:
         """Get the scaling factors from a dataset to its lower resolution."""
         if self.levels == 1:
-            return [1.0] * len(self.axes_mapper.on_disk_axes_names)
+            return [1.0] * len(self.axes_handler.axes_names)
         dataset, lr_dataset = self._get_closest_datasets(path=path)
 
         scaling_factors = []
-        for ax_name in self.axes_mapper.on_disk_axes_names:
+        for ax_name in self.axes_handler.axes_names:
             s_d = dataset.get_scale(ax_name)
             s_lr_d = lr_dataset.get_scale(ax_name)
             scaling_factors.append(s_lr_d / s_d)
@@ -359,8 +367,8 @@ class AbstractNgioImageMeta:
             return 1.0
         dataset, lr_dataset = self._get_closest_datasets(path=path)
 
-        s_d = dataset.get_scale("z")
-        s_lr_d = lr_dataset.get_scale("z")
+        s_d = dataset.get_scale("z", default=1.0)
+        s_lr_d = lr_dataset.get_scale("z", default=1.0)
         return s_lr_d / s_d
 
 
@@ -462,62 +470,5 @@ class NgioImageMeta(AbstractNgioImageMeta):
         )
         self.set_channels_meta(channels_meta=channels_meta)
 
-    @property
-    def channels(self) -> list[Channel]:
-        """Get the channels in the image."""
-        if self._channels_meta is None:
-            return []
-        assert self.channels_meta is not None
-        return self.channels_meta.channels
-
-    @property
-    def channel_labels(self) -> list[str]:
-        """Get the labels of the channels in the image."""
-        return [channel.label for channel in self.channels]
-
-    @property
-    def channel_wavelength_ids(self) -> list[str | None]:
-        """Get the wavelength IDs of the channels in the image."""
-        return [channel.wavelength_id for channel in self.channels]
-
-    def _get_channel_idx_by_label(self, label: str) -> int | None:
-        """Get the index of a channel by its label."""
-        if self._channels_meta is None:
-            return None
-
-        if label not in self.channel_labels:
-            raise NgioValueError(f"Channel with label {label} not found.")
-
-        return self.channel_labels.index(label)
-
-    def _get_channel_idx_by_wavelength_id(self, wavelength_id: str) -> int | None:
-        """Get the index of a channel by its wavelength ID."""
-        if self._channels_meta is None:
-            return None
-
-        if wavelength_id not in self.channel_wavelength_ids:
-            raise NgioValueError(
-                f"Channel with wavelength ID {wavelength_id} not found."
-            )
-
-        return self.channel_wavelength_ids.index(wavelength_id)
-
-    def get_channel_idx(
-        self, label: str | None = None, wavelength_id: str | None = None
-    ) -> int | None:
-        """Get the index of a channel by its label or wavelength ID."""
-        # Only one of the arguments must be provided
-        if sum([label is not None, wavelength_id is not None]) != 1:
-            raise NgioValueError("get_channel_idx must receive only one argument.")
-
-        if label is not None:
-            return self._get_channel_idx_by_label(label)
-        elif wavelength_id is not None:
-            return self._get_channel_idx_by_wavelength_id(wavelength_id)
-        else:
-            raise NgioValueError(
-                "get_channel_idx must receive either label or wavelength_id."
-            )
-
 
 NgioImageLabelMeta = NgioImageMeta | NgioLabelMeta

ngio/ome_zarr_meta/ngio_specs/_pixel_size.py

@@ -2,6 +2,7 @@
 
 import math
 from functools import total_ordering
+from typing import overload
 
 import numpy as np
 
@@ -84,10 +85,25 @@ class PixelSize:
         )
         return self.distance(ref) < other.distance(ref)
 
-    def as_dict(self) -> dict:
+    def as_dict(self) -> dict[str, float]:
         """Return the pixel size as a dictionary."""
         return {"t": self.t, "z": self.z, "y": self.y, "x": self.x}
 
+    @overload
+    def get(self, axis: str, default: float) -> float: ...
+
+    @overload
+    def get(self, axis: str, default: None = None) -> float | None: ...
+
+    def get(self, axis: str, default: float | None = None) -> float | None:
+        """Get the pixel size for a given axis (in canonical name)."""
+        px_size = self.as_dict().get(axis, default)
+        if px_size is None:
+            raise ValueError(
+                f"Invalid axis name: {axis}, must be one of 'x', 'y', 'z', 't'."
+            )
+        return px_size
+
     @property
     def space_unit(self) -> SpaceUnits | str | None:
         """Return the space unit."""

ngio/ome_zarr_meta/v04/_v04_spec_utils.py

@@ -26,6 +26,7 @@ from ome_zarr_models.v04.omero import Window as WindowV04
 from pydantic import ValidationError
 
 from ngio.ome_zarr_meta.ngio_specs import (
+    AxesHandler,
     AxesSetup,
     Axis,
     AxisType,
@@ -160,34 +161,38 @@ def _v04_to_ngio_datasets(
             v04_multiscale.coordinateTransformations, global_scale, global_translation
         )
 
-    for v04_dataset in v04_multiscale.datasets:
-        axes = []
-        for v04_axis in v04_multiscale.axes:
-            unit = v04_axis.unit
-            if unit is not None and not isinstance(unit, str):
-                unit = str(unit)
-            axes.append(
-                Axis(
-                    on_disk_name=v04_axis.name,
-                    axis_type=AxisType(v04_axis.type),
-                    # (for some reason the type is a generic JsonValue,
-                    # but it should be a string or None)
-                    unit=v04_axis.unit,  # type: ignore
-                )
+    # Prepare axes handler
+    axes = []
+    for v04_axis in v04_multiscale.axes:
+        unit = v04_axis.unit
+        if unit is not None and not isinstance(unit, str):
+            unit = str(unit)
+        axes.append(
+            Axis(
+                name=v04_axis.name,
+                axis_type=AxisType(v04_axis.type),
+                # (for some reason the type is a generic JsonValue,
+                # but it should be a string or None)
+                unit=v04_axis.unit,  # type: ignore
             )
+        )
+    axes_handler = AxesHandler(
+        axes=axes,
+        axes_setup=axes_setup,
+        allow_non_canonical_axes=allow_non_canonical_axes,
+        strict_canonical_order=strict_canonical_order,
+    )
 
-        _on_disk_scale, _on_disk_translation = _compute_scale_translation(
+    for v04_dataset in v04_multiscale.datasets:
+        _scale, _translation = _compute_scale_translation(
             v04_dataset.coordinateTransformations, global_scale, global_translation
         )
         datasets.append(
             Dataset(
                 path=v04_dataset.path,
-                on_disk_axes=axes,
-                on_disk_scale=_on_disk_scale,
-                on_disk_translation=_on_disk_translation,
-                axes_setup=axes_setup,
-                allow_non_canonical_axes=allow_non_canonical_axes,
-                strict_canonical_order=strict_canonical_order,
+                axes_handler=axes_handler,
+                scale=_scale,
+                translation=_translation,
             )
         )
     return datasets
@@ -314,12 +319,12 @@ def _ngio_to_v04_multiscale(name: str | None, datasets: list[Dataset]) -> Multis
     Returns:
         MultiscaleV04: The v04 multiscale.
     """
-    ax_mapper = datasets[0].axes_mapper
+    ax_mapper = datasets[0].axes_handler
     v04_axes = []
-    for axis in ax_mapper.on_disk_axes:
+    for axis in ax_mapper.axes:
         v04_axes.append(
             AxisV04(
-                name=axis.on_disk_name,
+                name=axis.name,
                 type=axis.axis_type.value if axis.axis_type is not None else None,
                 unit=axis.unit if axis.unit is not None else None,
             )
@@ -327,18 +332,16 @@ def _ngio_to_v04_multiscale(name: str | None, datasets: list[Dataset]) -> Multis
 
     v04_datasets = []
     for dataset in datasets:
-        transform = [VectorScaleV04(type="scale", scale=list(dataset._on_disk_scale))]
-        if sum(dataset._on_disk_translation) > 0:
+        transform = [VectorScaleV04(type="scale", scale=list(dataset._scale))]
+        if sum(dataset._translation) > 0:
             transform = (
-                VectorScaleV04(type="scale", scale=list(dataset._on_disk_scale)),
+                VectorScaleV04(type="scale", scale=list(dataset._scale)),
                 VectorTranslationV04(
-                    type="translation", translation=list(dataset._on_disk_translation)
+                    type="translation", translation=list(dataset._translation)
                 ),
             )
         else:
-            transform = (
-                VectorScaleV04(type="scale", scale=list(dataset._on_disk_scale)),
-            )
+            transform = (VectorScaleV04(type="scale", scale=list(dataset._scale)),)
 
         v04_datasets.append(
             DatasetV04(path=dataset.path, coordinateTransformations=transform)