ngio 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

ngio/__init__.py

@@ -10,7 +10,14 @@ __author__ = "Lorenzo Cerrone"
 __email__ = "lorenzo.cerrone@uzh.ch"
 
 from ngio.common import ArrayLike, Dimensions, Roi, RoiPixels
-from ngio.hcs import OmeZarrPlate, create_empty_plate, open_ome_zarr_plate
+from ngio.hcs import (
+    OmeZarrPlate,
+    OmeZarrWell,
+    create_empty_plate,
+    create_empty_well,
+    open_ome_zarr_plate,
+    open_ome_zarr_well,
+)
 from ngio.images import (
     Image,
     Label,
@@ -20,24 +27,35 @@ from ngio.images import (
     open_image,
     open_ome_zarr_container,
 )
-from ngio.ome_zarr_meta.ngio_specs import AxesSetup, ImageInWellPath, PixelSize
+from ngio.ome_zarr_meta.ngio_specs import (
+    AxesSetup,
+    DefaultNgffVersion,
+    ImageInWellPath,
+    NgffVersions,
+    PixelSize,
+)
 
 __all__ = [
     "ArrayLike",
     "AxesSetup",
+    "DefaultNgffVersion",
     "Dimensions",
     "Image",
     "ImageInWellPath",
     "Label",
+    "NgffVersions",
     "OmeZarrContainer",
     "OmeZarrPlate",
+    "OmeZarrWell",
     "PixelSize",
     "Roi",
     "RoiPixels",
     "create_empty_ome_zarr",
     "create_empty_plate",
+    "create_empty_well",
     "create_ome_zarr_from_array",
     "open_image",
     "open_ome_zarr_container",
     "open_ome_zarr_plate",
+    "open_ome_zarr_well",
 ]

ngio/common/_roi.py

@@ -10,7 +10,7 @@ import numpy as np
 from pydantic import BaseModel, ConfigDict, Field
 
 from ngio.common._dimensions import Dimensions
-from ngio.ome_zarr_meta.ngio_specs import PixelSize, SpaceUnits
+from ngio.ome_zarr_meta.ngio_specs import DefaultSpaceUnit, PixelSize, SpaceUnits
 from ngio.utils import NgioValueError
 
 
@@ -36,7 +36,7 @@ class Roi(BaseModel):
     x: float = 0.0
     y: float = 0.0
     z: float = 0.0
-    unit: SpaceUnits = Field(SpaceUnits.micrometer, repr=False)
+    unit: SpaceUnits | str | None = Field(DefaultSpaceUnit, repr=False)
 
     model_config = ConfigDict(extra="allow")
 

ngio/hcs/__init__.py

@@ -1,5 +1,19 @@
 """OME-Zarr HCS objects models."""
 
-from ngio.hcs.plate import OmeZarrPlate, create_empty_plate, open_ome_zarr_plate
+from ngio.hcs.plate import (
+    OmeZarrPlate,
+    OmeZarrWell,
+    create_empty_plate,
+    create_empty_well,
+    open_ome_zarr_plate,
+    open_ome_zarr_well,
+)
 
-__all__ = ["OmeZarrPlate", "create_empty_plate", "open_ome_zarr_plate"]
+__all__ = [
+    "OmeZarrPlate",
+    "OmeZarrWell",
+    "create_empty_plate",
+    "create_empty_well",
+    "open_ome_zarr_plate",
+    "open_ome_zarr_well",
+]

ngio/hcs/plate.py

@@ -3,19 +3,16 @@
 from ngio.images import OmeZarrContainer
 from ngio.ome_zarr_meta import (
     ImageInWellPath,
-    NgffVersion,
+    NgffVersions,
     NgioPlateMeta,
     NgioWellMeta,
     find_plate_meta_handler,
     find_well_meta_handler,
     get_plate_meta_handler,
     get_well_meta_handler,
+    path_in_well_validation,
 )
-from ngio.utils import (
-    AccessModeLiteral,
-    StoreOrGroup,
-    ZarrGroupHandler,
-)
+from ngio.utils import AccessModeLiteral, StoreOrGroup, ZarrGroupHandler
 
 
 # Mock lock class that does nothing
@@ -43,6 +40,10 @@ class OmeZarrWell:
         self._group_handler = group_handler
         self._meta_handler = find_well_meta_handler(group_handler)
 
+    def __repr__(self) -> str:
+        """Return a string representation of the well."""
+        return f"Well(#images: {len(self.paths())})"
+
     @property
     def meta_handler(self):
         """Return the metadata handler."""
@@ -53,6 +54,11 @@ class OmeZarrWell:
         """Return the metadata."""
         return self._meta_handler.meta
 
+    @property
+    def acquisition_ids(self) -> list[int]:
+        """Return the acquisitions ids in the well."""
+        return self.meta.acquisition_ids
+
     def paths(self, acquisition: int | None = None) -> list[str]:
         """Return the images paths in the well.
 
@@ -64,6 +70,97 @@ class OmeZarrWell:
         """
         return self.meta.paths(acquisition)
 
+    def get_image_store(self, image_path: str) -> StoreOrGroup:
+        """Get the image store from the well.
+
+        Args:
+            image_path (str): The path of the image.
+        """
+        return self._group_handler.get_group(image_path, create_mode=True)
+
+    def get_image_acquisition_id(self, image_path: str) -> int | None:
+        """Get the acquisition id of an image in the well.
+
+        Args:
+            image_path (str): The path of the image.
+
+        Returns:
+            int | None: The acquisition id of the image.
+        """
+        return self.meta.get_image_acquisition_id(image_path=image_path)
+
+    def get_image(self, image_path: str) -> OmeZarrContainer:
+        """Get an image from the well.
+
+        Args:
+            image_path (str): The path of the image.
+
+        Returns:
+            OmeZarrContainer: The image.
+        """
+        handler = self._group_handler.derive_handler(image_path)
+        return OmeZarrContainer(handler)
+
+    def _add_image(
+        self,
+        image_path: str,
+        acquisition_id: int | None = None,
+        strict: bool = True,
+        atomic: bool = False,
+    ) -> StoreOrGroup:
+        """Add an image to an ome-zarr well."""
+        image_path = path_in_well_validation(path=image_path)
+
+        if atomic:
+            well_lock = self._group_handler.lock
+        else:
+            well_lock = MockLock()
+
+        with well_lock:
+            meta = self.meta.add_image(
+                path=image_path, acquisition=acquisition_id, strict=strict
+            )
+            self.meta_handler.write_meta(meta)
+            self.meta_handler._group_handler.clean_cache()
+
+        return self._group_handler.get_group(image_path, create_mode=True)
+
+    def atomic_add_image(
+        self,
+        image_path: str,
+        acquisition_id: int | None = None,
+        strict: bool = True,
+    ) -> StoreOrGroup:
+        """Parallel safe version of add_image."""
+        return self._add_image(
+            image_path=image_path,
+            acquisition_id=acquisition_id,
+            atomic=True,
+            strict=strict,
+        )
+
+    def add_image(
+        self,
+        image_path: str,
+        acquisition_id: int | None = None,
+        strict: bool = True,
+    ) -> StoreOrGroup:
+        """Add an image to an ome-zarr well.
+
+        Args:
+            image_path (str): The path of the image.
+            acquisition_id (int | None): The acquisition id to filter the images.
+            strict (bool): Whether to check if the acquisition id is already exists
+                in the well. Defaults to True. If False this might lead to
+                acquision in a well that does not exist at the plate level.
+        """
+        return self._add_image(
+            image_path=image_path,
+            acquisition_id=acquisition_id,
+            atomic=False,
+            strict=strict,
+        )
+
 
 class OmeZarrPlate:
     """A class to handle the Plate Collection in an OME-Zarr file."""
@@ -107,9 +204,9 @@ class OmeZarrPlate:
         return self.meta.acquisitions_names
 
     @property
-    def acquisitions_ids(self) -> list[int]:
+    def acquisition_ids(self) -> list[int]:
         """Return the acquisitions ids in the plate."""
-        return self.meta.acquisitions_ids
+        return self.meta.acquisition_ids
 
     def _well_path(self, row: str, column: int | str) -> str:
         """Return the well path in the plate."""
@@ -160,6 +257,22 @@ class OmeZarrPlate:
             images.append(self._image_path(row=row, column=column, path=path))
         return images
 
+    def get_image_acquisition_id(
+        self, row: str, column: int | str, image_path: str
+    ) -> int | None:
+        """Get the acquisition id of an image in a well.
+
+        Args:
+            row (str): The row of the well.
+            column (int | str): The column of the well.
+            image_path (str): The path of the image.
+
+        Returns:
+            int | None: The acquisition id of the image.
+        """
+        well = self.get_well(row=row, column=column)
+        return well.get_image_acquisition_id(image_path=image_path)
+
     def get_well(self, row: str, column: int | str) -> OmeZarrWell:
         """Get a well from the plate.
 
@@ -217,6 +330,19 @@ class OmeZarrPlate:
         group_handler = self._group_handler.derive_handler(image_path)
         return OmeZarrContainer(group_handler)
 
+    def get_image_store(
+        self, row: str, column: int | str, image_path: str
+    ) -> StoreOrGroup:
+        """Get the image store from the plate.
+
+        Args:
+            row (str): The row of the well.
+            column (int | str): The column of the well.
+            image_path (str): The path of the image.
+        """
+        well = self.get_well(row=row, column=column)
+        return well.get_image_store(image_path=image_path)
+
     def get_well_images(
         self, row: str, column: str | int, acquisition: int | None = None
     ) -> dict[str, OmeZarrContainer]:
@@ -239,12 +365,15 @@ class OmeZarrPlate:
         self,
         row: str,
         column: int | str,
-        image_path: str,
+        image_path: str | None = None,
         acquisition_id: int | None = None,
         acquisition_name: str | None = None,
         atomic: bool = False,
-    ) -> StoreOrGroup:
+    ) -> StoreOrGroup | None:
         """Add an image to an ome-zarr plate."""
+        if image_path is not None:
+            image_path = path_in_well_validation(path=image_path)
+
         if atomic:
             plate_lock = self._group_handler.lock
         else:
@@ -252,7 +381,11 @@ class OmeZarrPlate:
 
         with plate_lock:
             meta = self.meta
-            meta = meta.add_well(row, column, acquisition_id, acquisition_name)
+            meta = meta.add_well(row=row, column=column)
+            if acquisition_id is not None:
+                meta = meta.add_acquisition(
+                    acquisition_id=acquisition_id, acquisition_name=acquisition_name
+                )
             self.meta_handler.write_meta(meta)
             self.meta_handler._group_handler.clean_cache()
 
@@ -279,11 +412,16 @@ class OmeZarrPlate:
 
             group_handler = self._group_handler.derive_handler(well_path)
 
-            well_meta = well_meta.add_image(path=image_path, acquisition=acquisition_id)
+            if image_path is not None:
+                well_meta = well_meta.add_image(
+                    path=image_path, acquisition=acquisition_id, strict=False
+                )
             meta_handler.write_meta(well_meta)
             meta_handler._group_handler.clean_cache()
 
-        return group_handler.get_group(image_path, create_mode=True)
+        if image_path is not None:
+            return group_handler.get_group(image_path, create_mode=True)
+        return None
 
     def atomic_add_image(
         self,
@@ -294,7 +432,12 @@ class OmeZarrPlate:
         acquisition_name: str | None = None,
     ) -> StoreOrGroup:
         """Parallel safe version of add_image."""
-        return self._add_image(
+        if image_path is None:
+            raise ValueError(
+                "Image path cannot be None for atomic add_image. "
+                "If your intent is to add a well, use add_well instead."
+            )
+        group = self._add_image(
             row=row,
             column=column,
             image_path=image_path,
@@ -302,6 +445,12 @@ class OmeZarrPlate:
             acquisition_name=acquisition_name,
             atomic=True,
         )
+        if group is None:
+            raise ValueError(
+                f"Some error occurred while adding image {image_path} "
+                f"to well {row}{column}."
+            )
+        return group
 
     def add_image(
         self,
@@ -312,7 +461,12 @@ class OmeZarrPlate:
         acquisition_name: str | None = None,
     ) -> StoreOrGroup:
         """Add an image to an ome-zarr plate."""
-        return self._add_image(
+        if image_path is None:
+            raise ValueError(
+                "Image path cannot be None for atomic add_image. "
+                "If your intent is to add a well, use add_well instead."
+            )
+        group = self._add_image(
             row=row,
             column=column,
             image_path=image_path,
@@ -320,6 +474,68 @@ class OmeZarrPlate:
             acquisition_name=acquisition_name,
             atomic=False,
         )
+        if group is None:
+            raise ValueError(
+                f"Some error occurred while adding image {image_path} "
+                f"to well {row}{column}."
+            )
+        return group
+
+    def add_well(
+        self,
+        row: str,
+        column: int | str,
+    ) -> OmeZarrWell:
+        """Add a well to an ome-zarr plate."""
+        _ = self._add_image(
+            row=row,
+            column=column,
+            image_path=None,
+            acquisition_id=None,
+            acquisition_name=None,
+            atomic=False,
+        )
+        return self.get_well(row=row, column=column)
+
+    def add_column(
+        self,
+        column: int | str,
+    ) -> "OmeZarrPlate":
+        """Add a column to an ome-zarr plate."""
+        meta, _ = self.meta.add_column(column)
+        self.meta_handler.write_meta(meta)
+        self.meta_handler._group_handler.clean_cache()
+        return self
+
+    def add_row(
+        self,
+        row: str,
+    ) -> "OmeZarrPlate":
+        """Add a row to an ome-zarr plate."""
+        meta, _ = self.meta.add_row(row)
+        self.meta_handler.write_meta(meta)
+        self.meta_handler._group_handler.clean_cache()
+        return self
+
+    def add_acquisition(
+        self,
+        acquisition_id: int,
+        acquisition_name: str,
+    ) -> "OmeZarrPlate":
+        """Add an acquisition to an ome-zarr plate.
+
+        Be aware that this is not a parallel safe operation.
+
+        Args:
+            acquisition_id (int): The acquisition id.
+            acquisition_name (str): The acquisition name.
+        """
+        meta = self.meta.add_acquisition(
+            acquisition_id=acquisition_id, acquisition_name=acquisition_name
+        )
+        self.meta_handler.write_meta(meta)
+        self.meta_handler._group_handler.clean_cache()
+        return self
 
     def _remove_well(
         self,
@@ -390,6 +606,38 @@ class OmeZarrPlate:
             atomic=False,
         )
 
+    def derive_plate(
+        self,
+        store: StoreOrGroup,
+        plate_name: str | None = None,
+        version: NgffVersions = "0.4",
+        keep_acquisitions: bool = False,
+        cache: bool = False,
+        overwrite: bool = False,
+        parallel_safe: bool = True,
+    ) -> "OmeZarrPlate":
+        """Derive a new OME-Zarr plate from an existing one.
+
+        Args:
+            store (StoreOrGroup): The Zarr store or group that stores the plate.
+            plate_name (str | None): The name of the new plate.
+            version (NgffVersion): The version of the new plate.
+            keep_acquisitions (bool): Whether to keep the acquisitions in the new plate.
+            cache (bool): Whether to use a cache for the zarr group metadata.
+            overwrite (bool): Whether to overwrite the existing plate.
+            parallel_safe (bool): Whether the group handler is parallel safe.
+        """
+        return derive_ome_zarr_plate(
+            ome_zarr_plate=self,
+            store=store,
+            plate_name=plate_name,
+            version=version,
+            keep_acquisitions=keep_acquisitions,
+            cache=cache,
+            overwrite=overwrite,
+            parallel_safe=parallel_safe,
+        )
+
 
 def open_ome_zarr_plate(
     store: StoreOrGroup,
@@ -412,26 +660,42 @@ def open_ome_zarr_plate(
     return OmeZarrPlate(group_handler)
 
 
+def _create_empty_plate_from_meta(
+    store: StoreOrGroup,
+    meta: NgioPlateMeta,
+    version: NgffVersions = "0.4",
+    overwrite: bool = False,
+) -> ZarrGroupHandler:
+    """Create an empty OME-Zarr plate from metadata."""
+    mode = "w" if overwrite else "w-"
+    group_handler = ZarrGroupHandler(
+        store=store, cache=True, mode=mode, parallel_safe=False
+    )
+    meta_handler = get_plate_meta_handler(group_handler, version=version)
+    meta_handler.write_meta(meta)
+    return group_handler
+
+
 def create_empty_plate(
     store: StoreOrGroup,
     name: str,
     images: list[ImageInWellPath] | None = None,
-    version: NgffVersion = "0.4",
+    version: NgffVersions = "0.4",
     cache: bool = False,
     overwrite: bool = False,
     parallel_safe: bool = True,
 ) -> OmeZarrPlate:
     """Initialize and create an empty OME-Zarr plate."""
-    mode = "w" if overwrite else "w-"
-    group_handler = ZarrGroupHandler(
-        store=store, cache=True, mode=mode, parallel_safe=False
-    )
-    meta_handler = get_plate_meta_handler(group_handler, version=version)
     plate_meta = NgioPlateMeta.default_init(
         name=name,
         version=version,
     )
-    meta_handler.write_meta(plate_meta)
+    group_handler = _create_empty_plate_from_meta(
+        store=store,
+        meta=plate_meta,
+        version=version,
+        overwrite=overwrite,
+    )
 
     if images is not None:
         plate = OmeZarrPlate(group_handler)
@@ -449,3 +713,98 @@ def create_empty_plate(
         mode="r+",
         parallel_safe=parallel_safe,
     )
+
+
+def derive_ome_zarr_plate(
+    ome_zarr_plate: OmeZarrPlate,
+    store: StoreOrGroup,
+    plate_name: str | None = None,
+    version: NgffVersions = "0.4",
+    keep_acquisitions: bool = False,
+    cache: bool = False,
+    overwrite: bool = False,
+    parallel_safe: bool = True,
+) -> OmeZarrPlate:
+    """Derive a new OME-Zarr plate from an existing one.
+
+    Args:
+        ome_zarr_plate (OmeZarrPlate): The existing OME-Zarr plate.
+        store (StoreOrGroup): The Zarr store or group that stores the plate.
+        plate_name (str | None): The name of the new plate.
+        version (NgffVersion): The version of the new plate.
+        keep_acquisitions (bool): Whether to keep the acquisitions in the new plate.
+        cache (bool): Whether to use a cache for the zarr group metadata.
+        overwrite (bool): Whether to overwrite the existing plate.
+        parallel_safe (bool): Whether the group handler is parallel safe.
+    """
+    if plate_name is None:
+        plate_name = ome_zarr_plate.meta.plate.name
+
+    new_meta = ome_zarr_plate.meta.derive(
+        name=plate_name,
+        version=version,
+        keep_acquisitions=keep_acquisitions,
+    )
+    _ = _create_empty_plate_from_meta(
+        store=store,
+        meta=new_meta,
+        overwrite=overwrite,
+        version=version,
+    )
+    return open_ome_zarr_plate(
+        store=store,
+        cache=cache,
+        mode="r+",
+        parallel_safe=parallel_safe,
+    )
+
+
+def open_ome_zarr_well(
+    store: StoreOrGroup,
+    cache: bool = False,
+    mode: AccessModeLiteral = "r+",
+    parallel_safe: bool = True,
+) -> OmeZarrWell:
+    """Open an OME-Zarr well.
+
+    Args:
+        store (StoreOrGroup): The Zarr store or group that stores the plate.
+        cache (bool): Whether to use a cache for the zarr group metadata.
+        mode (AccessModeLiteral): The access mode for the image. Defaults to "r+".
+        parallel_safe (bool): Whether the group handler is parallel safe.
+    """
+    group_handler = ZarrGroupHandler(
+        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
+    )
+    return OmeZarrWell(group_handler)
+
+
+def create_empty_well(
+    store: StoreOrGroup,
+    version: NgffVersions = "0.4",
+    cache: bool = False,
+    overwrite: bool = False,
+    parallel_safe: bool = True,
+) -> OmeZarrWell:
+    """Create an empty OME-Zarr well.
+
+    Args:
+        store (StoreOrGroup): The Zarr store or group that stores the well.
+        version (NgffVersion): The version of the new well.
+        cache (bool): Whether to use a cache for the zarr group metadata.
+        overwrite (bool): Whether to overwrite the existing well.
+        parallel_safe (bool): Whether the group handler is parallel safe.
+    """
+    group_handler = ZarrGroupHandler(
+        store=store, cache=True, mode="w" if overwrite else "w-", parallel_safe=False
+    )
+    meta_handler = get_well_meta_handler(group_handler, version=version)
+    meta = NgioWellMeta.default_init()
+    meta_handler.write_meta(meta)
+
+    return open_ome_zarr_well(
+        store=store,
+        cache=cache,
+        mode="r+",
+        parallel_safe=parallel_safe,
+    )

ngio/images/abstract_image.py

@@ -135,6 +135,16 @@ class AbstractImage(Generic[_image_handler]):
         """Return True if the image is multichannel."""
         return self.dimensions.is_multi_channels
 
+    @property
+    def space_unit(self) -> str | None:
+        """Return the space unit of the image."""
+        return self.meta_handler.meta.space_unit
+
+    @property
+    def time_unit(self) -> str | None:
+        """Return the time unit of the image."""
+        return self.meta_handler.meta.time_unit
+
     @property
     def pixel_size(self) -> PixelSize:
         """Return the pixel size of the image."""