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

ngio/hcs/plate.py

@@ -1,23 +1,44 @@
 """A module for handling the Plate Collection in an OME-Zarr file."""
 
+from typing import Literal, overload
+
 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.tables import (
+    FeatureTable,
+    GenericRoiTable,
+    MaskingRoiTable,
+    RoiTable,
+    Table,
+    TablesContainer,
+    TypedTable,
 )
 from ngio.utils import (
     AccessModeLiteral,
+    NgioValidationError,
+    NgioValueError,
     StoreOrGroup,
     ZarrGroupHandler,
 )
 
 
+def _default_table_container(handler: ZarrGroupHandler) -> TablesContainer | None:
+    """Return a default table container."""
+    success, table_handler = handler.safe_derive_handler("tables")
+    if success and isinstance(table_handler, ZarrGroupHandler):
+        return TablesContainer(table_handler)
+
+
 # Mock lock class that does nothing
 class MockLock:
     """A mock lock class that does nothing."""
@@ -43,6 +64,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 +78,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,18 +94,115 @@ 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."""
 
-    def __init__(self, group_handler: ZarrGroupHandler) -> None:
+    def __init__(
+        self,
+        group_handler: ZarrGroupHandler,
+        table_container: TablesContainer | None = None,
+    ) -> None:
         """Initialize the LabelGroupHandler.
 
         Args:
             group_handler: The Zarr group handler that contains the Plate.
+            table_container: The tables container that contains plate level tables.
         """
         self._group_handler = group_handler
         self._meta_handler = find_plate_meta_handler(group_handler)
+        self._tables_container = table_container
 
     def __repr__(self) -> str:
         """Return a string representation of the plate."""
@@ -107,9 +234,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 +287,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 +360,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 +395,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 +411,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 +442,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 +462,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 +475,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 +491,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 +504,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 +636,127 @@ 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,
+        )
+
+    @property
+    def tables_container(self) -> TablesContainer:
+        """Return the tables container."""
+        if self._tables_container is None:
+            self._tables_container = _default_table_container(self._group_handler)
+            if self._tables_container is None:
+                raise NgioValidationError("No tables found in the image.")
+        return self._tables_container
+
+    @property
+    def list_tables(self) -> list[str]:
+        """List all tables in the image."""
+        return self.tables_container.list()
+
+    def list_roi_tables(self) -> list[str]:
+        """List all ROI tables in the image."""
+        return self.tables_container.list_roi_tables()
+
+    @overload
+    def get_table(self, name: str, check_type: None) -> Table: ...
+
+    @overload
+    def get_table(self, name: str, check_type: Literal["roi_table"]) -> RoiTable: ...
+
+    @overload
+    def get_table(
+        self, name: str, check_type: Literal["masking_roi_table"]
+    ) -> MaskingRoiTable: ...
+
+    @overload
+    def get_table(
+        self, name: str, check_type: Literal["feature_table"]
+    ) -> FeatureTable: ...
+
+    @overload
+    def get_table(
+        self, name: str, check_type: Literal["generic_roi_table"]
+    ) -> GenericRoiTable: ...
+
+    def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
+        """Get a table from the image."""
+        table = self.tables_container.get(name)
+        match check_type:
+            case "roi_table":
+                if not isinstance(table, RoiTable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a ROI table. Found type: {table.type()}"
+                    )
+                return table
+            case "masking_roi_table":
+                if not isinstance(table, MaskingRoiTable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a masking ROI table. "
+                        f"Found type: {table.type()}"
+                    )
+                return table
+
+            case "generic_roi_table":
+                if not isinstance(table, GenericRoiTable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a generic ROI table. "
+                        f"Found type: {table.type()}"
+                    )
+                return table
+
+            case "feature_table":
+                if not isinstance(table, FeatureTable):
+                    raise NgioValueError(
+                        f"Table '{name}' is not a feature table. "
+                        f"Found type: {table.type()}"
+                    )
+                return table
+            case None:
+                return table
+            case _:
+                raise NgioValueError(f"Unknown check_type: {check_type}")
+
+    def add_table(
+        self,
+        name: str,
+        table: Table,
+        backend: str | None = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Add a table to the image."""
+        self.tables_container.add(
+            name=name, table=table, backend=backend, overwrite=overwrite
+        )
+
 
 def open_ome_zarr_plate(
     store: StoreOrGroup,
@@ -412,26 +779,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 +832,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."""
@@ -152,6 +162,7 @@ class AbstractImage(Generic[_image_handler]):
 
     def has_axis(self, axis: str) -> bool:
         """Return True if the image has the given axis."""
+        self.axes_mapper.get_index("x")
         return self.dimensions.has_axis(axis)
 
     def get_array(