ngio 0.4.7__py3-none-any.whl → 0.5.0__py3-none-any.whl

ngio/ome_zarr_meta/ngio_specs/_ngio_hcs.py

@@ -1,32 +1,31 @@
 """HCS (High Content Screening) specific metadata classes for NGIO."""
 
+import warnings
 from typing import Annotated
 
-from ome_zarr_models.v04.hcs import HCSAttrs
-from ome_zarr_models.v04.plate import (
+from ome_zarr_models.common.plate import (
     Acquisition,
     Column,
-    Plate,
+    PlateBase,
     Row,
     WellInPlate,
 )
-from ome_zarr_models.v04.well import WellAttrs as WellAttrs04
-from ome_zarr_models.v04.well_types import WellImage as WellImage04
-from ome_zarr_models.v04.well_types import WellMeta as WellMeta04
+from ome_zarr_models.common.well_types import WellImage as WellImageCommon
 from pydantic import BaseModel, SkipValidation, field_serializer
 
 from ngio.ome_zarr_meta.ngio_specs._ngio_image import DefaultNgffVersion, NgffVersions
-from ngio.utils import NgioValueError, ngio_logger
+from ngio.utils import NgioValueError
 
 
 def path_in_well_validation(path: str) -> str:
     """Validate the path in the well."""
     # Check if the value contains only alphanumeric characters
     if not path.isalnum():
-        ngio_logger.warning(
+        warnings.warn(
             f"Path '{path}' contains non-alphanumeric characters. "
             "This may cause issues with some tools. "
-            "Consider using only alphanumeric characters in the path."
+            "Consider using only alphanumeric characters in the path.",
+            stacklevel=2,
         )
     return path
 
@@ -41,7 +40,7 @@ class ImageInWellPath(BaseModel):
     acquisition_name: str | None = None
 
 
-class CustomWellImage(WellImage04):
+class CustomWellImage(WellImageCommon):
     path: Annotated[str, SkipValidation]
 
     @field_serializer("path")
@@ -50,32 +49,29 @@ class CustomWellImage(WellImage04):
         return path_in_well_validation(value)
 
 
-class CustomWellMeta(WellMeta04):
-    images: list[CustomWellImage]  # type: ignore (override of WellMeta04.images)
-
+class PlateWithVersion(PlateBase):
+    version: NgffVersions
 
-class CustomWellAttrs(WellAttrs04):
-    well: CustomWellMeta  # type: ignore (override of WellAttrs04.well)
 
-
-class NgioWellMeta(CustomWellAttrs):
+class NgioWellMeta(BaseModel):
     """HCS well metadata."""
 
+    images: list[CustomWellImage]  # type: ignore (override of WellMeta04.images)
+    version: NgffVersions
+
     @classmethod
     def default_init(
         cls,
-        version: NgffVersions | None = None,
+        ngff_version: NgffVersions = DefaultNgffVersion,
     ) -> "NgioWellMeta":
-        if version is None:
-            version = DefaultNgffVersion
-        well = cls(well=CustomWellMeta(images=[], version=version))
+        well = cls(images=[], version=ngff_version)
         return well
 
     @property
     def acquisition_ids(self) -> list[int]:
         """Return the acquisition ids in the well."""
         acquisitions = []
-        for images in self.well.images:
+        for images in self.images:
             if (
                 images.acquisition is not None
                 and images.acquisition not in acquisitions
@@ -85,7 +81,7 @@ class NgioWellMeta(CustomWellAttrs):
 
     def get_image_acquisition_id(self, image_path: str) -> int | None:
         """Return the acquisition id for the given image path."""
-        for images in self.well.images:
+        for images in self.images:
             if images.path == image_path:
                 return images.acquisition
         raise NgioValueError(f"Image at path {image_path} not found in the well.")
@@ -100,11 +96,9 @@ class NgioWellMeta(CustomWellAttrs):
             acquisition (int | None): The acquisition id to filter the images.
         """
         if acquisition is None:
-            return [images.path for images in self.well.images]
+            return [images.path for images in self.images]
         return [
-            images.path
-            for images in self.well.images
-            if images.acquisition == acquisition
+            images.path for images in self.images if images.acquisition == acquisition
         ]
 
     def add_image(
@@ -118,7 +112,7 @@ class NgioWellMeta(CustomWellAttrs):
             strict (bool): If True, check if the image already exists in the well.
                 If False, do not check if the image already exists in the well.
         """
-        list_of_images = self.well.images
+        list_of_images = self.images
         for image in list_of_images:
             if image.path == path:
                 raise NgioValueError(
@@ -137,9 +131,7 @@ class NgioWellMeta(CustomWellAttrs):
 
         new_image = CustomWellImage(path=path, acquisition=acquisition)
         list_of_images.append(new_image)
-        return NgioWellMeta(
-            well=CustomWellMeta(images=list_of_images, version=self.well.version)
-        )
+        return NgioWellMeta(images=list_of_images, version=self.version)
 
     def remove_image(self, path: str) -> "NgioWellMeta":
         """Remove an image from the well.
@@ -147,35 +139,66 @@ class NgioWellMeta(CustomWellAttrs):
         Args:
             path (str): The path of the image.
         """
-        list_of_images = self.well.images
+        list_of_images = self.images
         for image in list_of_images:
             if image.path == path:
                 list_of_images.remove(image)
-                return NgioWellMeta(
-                    well=CustomWellMeta(
-                        images=list_of_images, version=self.well.version
-                    )
-                )
+                return NgioWellMeta(images=list_of_images, version=self.version)
         raise NgioValueError(f"Image at path {path} not found in the well.")
 
 
-def _stringify_column(column: str | int) -> str:
+def _format_int_column(column: int, num_digits: int = 2) -> str:
+    """Format the column as a string.
+
+    We make sure to pad the column with zeros
+    to have a consistent format.
+
+    Args:
+        column (int): The column to format.
+        num_digits (int): The number of digits to pad the column.
+
+    Returns:
+        str: The column as a string.
+    """
+    return f"{column:0{num_digits}d}"
+
+
+def _stringify_column(column: str | int, num_digits: int = 2) -> str:
     """Convert the column to a string.
 
+    This will ensure that columns are always strings.
+    and will help with sorting and comparison.
+
     Args:
         column (str | int): The column to convert.
+        num_digits (int): The number of digits to pad the column.
 
     Returns:
         str: The column as a string.
     """
-    if isinstance(column, str):
-        return column
+    if isinstance(column, int):
+        return _format_int_column(column, num_digits=num_digits)
 
-    # Maybe we should pad the column with zeros
-    return str(column)
+    elif isinstance(column, str):
+        try:
+            column_int = int(column)
+            return _format_int_column(column_int, num_digits=num_digits)
+        except ValueError:
+            pass
+        return column
+    raise NgioValueError(f"Column {column} must be a string or an integer.")
 
 
 def _find_row_index(rows: list[str], row: str) -> int | None:
+    """Find the index of a row in the list of rows.
+
+    Args:
+        rows: List of row names.
+        row: The row name to find.
+
+    Returns:
+        The index of the row, or None if not found.
+    """
     try:
         return rows.index(row)
     except ValueError:
@@ -183,8 +206,17 @@ def _find_row_index(rows: list[str], row: str) -> int | None:
 
 
 def _find_column_index(columns: list[str], column: str | int) -> int | None:
-    _num_columns = [int(columns) for columns in columns]
-    column = int(column)
+    """Find the index of a column in the list of columns.
+
+    Args:
+        columns: List of column names.
+        column: The column name or number to find.
+
+    Returns:
+        The index of the column, or None if not found.
+    """
+    _num_columns = [_stringify_column(columns) for columns in columns]
+    column = _stringify_column(column)
     try:
         return _num_columns.index(column)
     except ValueError:
@@ -194,6 +226,16 @@ def _find_column_index(columns: list[str], column: str | int) -> int | None:
 def _relabel_wells(
     wells: list[WellInPlate], rows: list[Row], columns: list[Column]
 ) -> list[WellInPlate]:
+    """Relabel well indices after rows or columns have been added.
+
+    Args:
+        wells: List of wells to relabel.
+        rows: Updated list of rows.
+        columns: Updated list of columns.
+
+    Returns:
+        List of wells with updated row and column indices.
+    """
     new_wells = []
     _rows = [row.name for row in rows]
     _columns = [column.name for column in columns]
@@ -218,26 +260,30 @@ def _relabel_wells(
     return new_wells
 
 
-class NgioPlateMeta(HCSAttrs):
+class NgioPlateMeta(BaseModel):
     """HCS plate metadata."""
 
+    plate: PlateWithVersion
+    version: NgffVersions
+
     @classmethod
     def default_init(
         cls,
         images: list[ImageInWellPath] | None = None,
         name: str | None = None,
-        version: NgffVersions | None = None,
+        ngff_version: NgffVersions = DefaultNgffVersion,
     ) -> "NgioPlateMeta":
         plate = cls(
-            plate=Plate(
+            plate=PlateWithVersion(
                 rows=[],
                 columns=[],
                 acquisitions=None,
                 wells=[],
                 field_count=None,
-                version=version,
                 name=name,
-            )
+                version=ngff_version,
+            ),
+            version=ngff_version,
         )
 
         if images is None:
@@ -294,23 +340,8 @@ class NgioPlateMeta(HCSAttrs):
         Returns:
             str: The path of the well.
         """
-        if row not in self.rows:
-            raise NgioValueError(
-                f"Row {row} not found in the plate. Available rows are {self.rows}."
-            )
-
-        row_idx = self.rows.index(row)
-
-        _num_columns = [int(columns) for columns in self.columns]
-
-        try:
-            _column = int(column)
-        except ValueError:
-            raise NgioValueError(
-                f"Column {column} must be an integer or convertible to an integer."
-            ) from None
-
-        column_idx = _num_columns.index(_column)
+        row_idx = _find_row_index(self.rows, row)
+        column_idx = _find_column_index(self.columns, column)
 
         for well in self.plate.wells:
             if well.columnIndex == column_idx and well.rowIndex == row_idx:
@@ -346,16 +377,16 @@ class NgioPlateMeta(HCSAttrs):
         else:
             wells = self.plate.wells
 
-        new_plate = Plate(
+        new_plate = PlateWithVersion(
             rows=rows,
             columns=self.plate.columns,
             acquisitions=self.plate.acquisitions,
             wells=wells,
             field_count=self.plate.field_count,
             name=self.plate.name,
-            version=self.plate.version,
+            version=self.version,
         )
-        return NgioPlateMeta(plate=new_plate), row_idx
+        return NgioPlateMeta(plate=new_plate, version=self.version), row_idx
 
     def add_column(self, column: str | int) -> "tuple[NgioPlateMeta, int]":
         """Add a column to the plate.
@@ -373,7 +404,7 @@ class NgioPlateMeta(HCSAttrs):
 
         columns_names.append(_stringify_column(column))
         # sort as numbers
-        columns_names.sort(key=lambda x: int(x))
+        columns_names.sort(key=lambda x: _stringify_column(x))
         column_idx = columns_names.index(_stringify_column(column))
         relabel_wells = True
 
@@ -384,27 +415,30 @@ class NgioPlateMeta(HCSAttrs):
         else:
             wells = self.plate.wells
 
-        new_plate = Plate(
+        new_plate = PlateWithVersion(
             rows=self.plate.rows,
             columns=columns,
             acquisitions=self.plate.acquisitions,
             wells=wells,
             field_count=self.plate.field_count,
             name=self.plate.name,
-            version=self.plate.version,
+            version=self.version,
         )
-        return NgioPlateMeta(plate=new_plate), column_idx
+        return NgioPlateMeta(plate=new_plate, version=self.version), column_idx
 
     def add_well(
         self,
         row: str,
         column: str | int,
     ) -> "NgioPlateMeta":
-        """Add an image to the well.
+        """Add a well to the plate.
 
         Args:
             row (str): The row of the well.
             column (str | int): The column of the well.
+
+        Returns:
+            NgioPlateMeta: Updated plate metadata with the new well.
         """
         plate, row_idx = self.add_row(row=row)
         plate, column_idx = plate.add_column(column=column)
@@ -422,16 +456,16 @@ class NgioPlateMeta(HCSAttrs):
                 )
             )
 
-        new_plate = Plate(
+        new_plate = PlateWithVersion(
             rows=plate.plate.rows,
             columns=plate.plate.columns,
             acquisitions=plate.plate.acquisitions,
             wells=wells,
             field_count=plate.plate.field_count,
             name=plate.plate.name,
-            version=plate.plate.version,
+            version=plate.version,
         )
-        return NgioPlateMeta(plate=new_plate)
+        return NgioPlateMeta(plate=new_plate, version=plate.version)
 
     def add_acquisition(
         self,
@@ -461,16 +495,16 @@ class NgioPlateMeta(HCSAttrs):
             Acquisition(id=acquisition_id, name=acquisition_name, **acquisition_kwargs)
         )
 
-        new_plate = Plate(
+        new_plate = PlateWithVersion(
             rows=self.plate.rows,
             columns=self.plate.columns,
             acquisitions=acquisitions,
             wells=self.plate.wells,
             field_count=self.plate.field_count,
             name=self.plate.name,
-            version=self.plate.version,
+            version=self.version,
         )
-        return NgioPlateMeta(plate=new_plate)
+        return NgioPlateMeta(plate=new_plate, version=self.version)
 
     def remove_well(self, row: str, column: str | int) -> "NgioPlateMeta":
         """Remove a well from the plate.
@@ -497,30 +531,33 @@ class NgioPlateMeta(HCSAttrs):
                 f"Well at row {row} and column {column} not found in the plate."
             )
 
-        new_plate = Plate(
+        new_plate = PlateWithVersion(
             rows=self.plate.rows,
             columns=self.plate.columns,
             acquisitions=self.plate.acquisitions,
             wells=wells,
             field_count=self.plate.field_count,
             name=self.plate.name,
-            version=self.plate.version,
+            version=self.version,
         )
-        return NgioPlateMeta(plate=new_plate)
+        return NgioPlateMeta(plate=new_plate, version=self.version)
 
     def derive(
         self,
         name: str | None = None,
-        version: NgffVersions | None = None,
+        ngff_version: NgffVersions | None = None,
         keep_acquisitions: bool = False,
     ) -> "NgioPlateMeta":
         """Derive the plate metadata.
 
         Args:
-            name (str): The name of the derived plate.
-            version (NgffVersion | None): The version of the derived plate.
+            name (str | None): The name of the derived plate.
+            ngff_version (NgffVersions | None): The version of the derived plate.
                 If None, use the version of the original plate.
             keep_acquisitions (bool): If True, keep the acquisitions in the plate.
+
+        Returns:
+            NgioPlateMeta: The derived plate metadata.
         """
         columns = self.plate.columns
         rows = self.plate.rows
@@ -530,17 +567,18 @@ class NgioPlateMeta(HCSAttrs):
         else:
             acquisitions = None
 
-        if version is None:
-            version = self.plate.version  # type: ignore (version is NgffVersions or None)
+        if ngff_version is None:
+            ngff_version = self.version
 
         return NgioPlateMeta(
-            plate=Plate(
+            plate=PlateWithVersion(
                 rows=rows,
                 columns=columns,
                 acquisitions=acquisitions,
                 wells=[],
                 field_count=self.plate.field_count,
-                version=version,
                 name=name,
-            )
+                version=ngff_version,
+            ),
+            version=ngff_version,
         )

ngio/ome_zarr_meta/ngio_specs/_ngio_image.py

@@ -13,11 +13,11 @@ import numpy as np
 from pydantic import BaseModel
 
 from ngio.ome_zarr_meta.ngio_specs._axes import (
+    AxesHandler,
     DefaultSpaceUnit,
     DefaultTimeUnit,
     SpaceUnits,
     TimeUnits,
-    build_canonical_axes_handler,
 )
 from ngio.ome_zarr_meta.ngio_specs._channels import ChannelsMeta
 from ngio.ome_zarr_meta.ngio_specs._dataset import Dataset
@@ -25,7 +25,7 @@ from ngio.ome_zarr_meta.ngio_specs._pixel_size import PixelSize
 from ngio.utils import NgioValidationError, NgioValueError
 
 T = TypeVar("T")
-NgffVersions = Literal["0.4"]
+NgffVersions = Literal["0.4", "0.5"]
 DefaultNgffVersion: Literal["0.4"] = "0.4"
 
 
@@ -41,6 +41,13 @@ class ImageLabelSource(BaseModel):
         return cls(version=version, source={"image": "../../"})
 
 
+class NgioLabelsGroupMeta(BaseModel):
+    """Metadata model for the /labels group in OME-NGFF."""
+
+    version: NgffVersions
+    labels: list[str]
+
+
 class AbstractNgioImageMeta:
     """Base class for ImageMeta and LabelMeta."""
 
@@ -66,42 +73,23 @@ class AbstractNgioImageMeta:
     @classmethod
     def default_init(
         cls,
-        levels: int | Sequence[str],
-        axes_names: Sequence[str],
-        pixel_size: PixelSize,
-        scaling_factors: Sequence[float] | None = None,
+        levels: Sequence[str],
+        axes_handler: AxesHandler,
+        scales: Sequence[tuple[float, ...]],
+        translations: Sequence[tuple[float, ...] | None],
         name: str | None = None,
         version: NgffVersions = DefaultNgffVersion,
     ):
         """Initialize the ImageMeta object."""
-        axes_handler = build_canonical_axes_handler(
-            axes_names,
-            space_units=pixel_size.space_unit,
-            time_units=pixel_size.time_unit,
-        )
-
-        px_size_dict = pixel_size.as_dict()
-        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(name, 1.0) for name in axes_handler.axes_names
-            ]
-
-        if isinstance(levels, int):
-            levels = [str(i) for i in range(levels)]
-
         datasets = []
-        for level in levels:
+        for level, scale, translation in zip(levels, scales, translations, strict=True):
             dataset = Dataset(
                 path=level,
                 axes_handler=axes_handler,
                 scale=scale,
-                translation=None,
+                translation=translation,
             )
             datasets.append(dataset)
-            scale = [s * f for s, f in zip(scale, scaling_factors, strict=True)]
 
         return cls(
             version=version,
@@ -141,11 +129,58 @@ class AbstractNgioImageMeta:
             datasets=new_datasets,
         )
 
+    def rename_axes(self, axes_names: Sequence[str]):
+        """Rename axes in the metadata.
+
+        Args:
+            axes_names(Sequence[str]): The new axes names in the order of the current
+                axes.
+        """
+        new_axes_handler = self.axes_handler.rename_axes(axes_names=axes_names)
+        new_datasets = []
+        for dataset in self.datasets:
+            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)(
+            version=self.version,
+            name=self.name,
+            datasets=new_datasets,
+        )
+
+    def rename_image(self, name: str):
+        """Rename the image in the metadata.
+
+        Args:
+            name(str): The new name of the image.
+        """
+        return type(self)(
+            version=self.version,
+            name=name,
+            datasets=self.datasets,
+        )
+
     @property
     def version(self) -> NgffVersions:
         """Version of the OME-NFF metadata used to build the object."""
         return self._version  # type: ignore (version is a Literal type)
 
+    @property
+    def zarr_format(self) -> Literal[2, 3]:
+        """Zarr version used to store the data."""
+        match self.version:
+            case "0.4":
+                return 2
+            case "0.5":
+                return 3
+            case _:
+                raise NgioValueError(f"Unsupported NGFF version: {self.version}")
+
     @property
     def name(self) -> str | None:
         """Name of the image."""
@@ -326,50 +361,15 @@ class AbstractNgioImageMeta:
             )
         return dataset, lr_dataset
 
-    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_handler.axes_names)
-        dataset, lr_dataset = self._get_closest_datasets(path=path)
-
-        scaling_factors = []
-        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)
-        return scaling_factors
-
-    def yx_scaling(self, path: str | None = None) -> tuple[float, float]:
-        """Get the scaling factor from a dataset to its lower resolution."""
+    def scaling_factor(self, path: str | None = None) -> tuple[float, ...]:
+        """Get the scaling factors to downscale to the next lower resolution dataset."""
         if self.levels == 1:
-            return 1.0, 1.0
+            return (1.0,) * len(self.axes_handler.axes_names)
         dataset, lr_dataset = self._get_closest_datasets(path=path)
-
-        if lr_dataset is None:
-            raise NgioValueError(
-                "No lower resolution dataset found. "
-                "This is the lowest resolution dataset."
-            )
-
-        s_d = dataset.get_scale("y")
-        s_lr_d = lr_dataset.get_scale("y")
-        scale_y = s_lr_d / s_d
-
-        s_d = dataset.get_scale("x")
-        s_lr_d = lr_dataset.get_scale("x")
-        scale_x = s_lr_d / s_d
-
-        return scale_y, scale_x
-
-    def z_scaling(self, path: str | None = None) -> float:
-        """Get the scaling factor from a dataset to its lower resolution."""
-        if self.levels == 1:
-            return 1.0
-        dataset, lr_dataset = self._get_closest_datasets(path=path)
-
-        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
+        scale = dataset.scale
+        lr_scale = lr_dataset.scale
+        scaling_factors = [s / s_lr for s_lr, s in zip(scale, lr_scale, strict=True)]
+        return tuple(scaling_factors)
 
 
 class NgioLabelMeta(AbstractNgioImageMeta):