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

ngio/common/_pyramid.py

@@ -190,12 +190,16 @@ def init_empty_pyramid(
             "The shape and chunks must have the same number of dimensions."
         )
 
+    if chunks is not None:
+        chunks = [min(c, s) for c, s in zip(chunks, ref_shape, strict=True)]
+
     if len(ref_shape) != len(scaling_factors):
         raise NgioValueError(
             "The shape and scaling factor must have the same number of dimensions."
         )
 
-    root_group, _ = open_group_wrapper(store, mode=mode)
+    root_group = open_group_wrapper(store, mode=mode)
+
     for path in paths:
         if any(s < 1 for s in ref_shape):
             raise NgioValueError(

ngio/hcs/plate.py

@@ -1,5 +1,7 @@
 """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,
@@ -12,7 +14,29 @@ from ngio.ome_zarr_meta import (
     get_well_meta_handler,
     path_in_well_validation,
 )
-from ngio.utils import AccessModeLiteral, StoreOrGroup, ZarrGroupHandler
+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
@@ -165,14 +189,20 @@ class OmeZarrWell:
 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."""
@@ -638,6 +668,95 @@ class OmeZarrPlate:
             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,

ngio/images/abstract_image.py

@@ -162,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(

ngio/images/image.py

@@ -154,6 +154,8 @@ class ImagesContainer:
         self,
         labels: Collection[str] | int | None = None,
         wavelength_id: Collection[str] | None = None,
+        start: Collection[float] | None = None,
+        end: Collection[float] | None = None,
         percentiles: tuple[float, float] | None = None,
         colors: Collection[str] | None = None,
         active: Collection[bool] | None = None,
@@ -166,6 +168,10 @@ class ImagesContainer:
                 If an integer is provided, the channels will be named "channel_i".
             wavelength_id(Collection[str] | None): The wavelength ID of the channel.
                 If None, the wavelength ID will be the same as the channel name.
+            start(Collection[float] | None): The start value for each channel.
+                If None, the start value will be computed from the image.
+            end(Collection[float] | None): The end value for each channel.
+                If None, the end value will be computed from the image.
             percentiles(tuple[float, float] | None): The start and end percentiles
                 for each channel. If None, the percentiles will not be computed.
             colors(Collection[str, NgioColors] | None): The list of colors for the
@@ -177,12 +183,40 @@ class ImagesContainer:
         low_res_dataset = self.meta.get_lowest_resolution_dataset()
         ref_image = self.get(path=low_res_dataset.path)
 
+        if start is not None and end is None:
+            raise NgioValidationError(
+                "If start is provided, end must be provided as well."
+            )
+        if end is not None and start is None:
+            raise NgioValidationError(
+                "If end is provided, start must be provided as well."
+            )
+
+        if start is not None and percentiles is not None:
+            raise NgioValidationError(
+                "If start and end are provided, percentiles must be None."
+            )
+
         if percentiles is not None:
             start, end = compute_image_percentile(
                 ref_image,
                 start_percentile=percentiles[0],
                 end_percentile=percentiles[1],
             )
+        elif start is not None and end is not None:
+            if len(start) != len(end):
+                raise NgioValidationError(
+                    "The start and end lists must have the same length."
+                )
+            if len(start) != self.num_channels:
+                raise NgioValidationError(
+                    "The start and end lists must have the same length as "
+                    "the number of channels."
+                )
+
+            start = list(start)
+            end = list(end)
+
         else:
             start, end = None, None
 
@@ -462,11 +496,17 @@ def derive_image_container(
         active = [
             c.channel_visualisation.active for c in ref_image._channels_meta.channels
         ]
+        start = [
+            c.channel_visualisation.start for c in ref_image._channels_meta.channels
+        ]
+        end = [c.channel_visualisation.end for c in ref_image._channels_meta.channels]
     else:
         _labels = None
         wavelength_id = None
         colors = None
         active = None
+        start = None
+        end = None
 
     if labels is not None:
         if len(labels) != image_container.num_channels:
@@ -481,5 +521,7 @@ def derive_image_container(
         percentiles=None,
         colors=colors,
         active=active,
+        start=start,
+        end=end,
     )
     return image_container

ngio/images/label.py

@@ -133,6 +133,12 @@ class LabelsContainer:
                 closest pixel size level will be returned.
 
         """
+        if name not in self.list():
+            raise NgioValueError(
+                f"Label '{name}' not found in the Labels group. "
+                f"Available labels: {self.list()}"
+            )
+
         group_handler = self._group_handler.derive_handler(name)
         label_meta_handler = find_label_meta_handler(group_handler)
         path = label_meta_handler.meta.get_dataset(
@@ -143,7 +149,7 @@ class LabelsContainer:
     def derive(
         self,
         name: str,
-        ref_image: Image,
+        ref_image: Image | Label,
         shape: Collection[int] | None = None,
         pixel_size: PixelSize | None = None,
         axes_names: Collection[str] | None = None,
@@ -157,7 +163,8 @@ class LabelsContainer:
 
         Args:
             store (StoreOrGroup): The Zarr store or group to create the image in.
-            ref_image (Image): The reference image.
+            ref_image (Image | Label): A reference image that will be used to create
+                the new image.
             name (str): The name of the new image.
             shape (Collection[int] | None): The shape of the new image.
             pixel_size (PixelSize | None): The pixel size of the new image.
@@ -174,13 +181,13 @@ class LabelsContainer:
         existing_labels = self.list()
         if name in existing_labels and not overwrite:
             raise NgioValueError(
-                f"Table '{name}' already exists in the group. "
+                f"Label '{name}' already exists in the group. "
                 "Use overwrite=True to replace it."
             )
 
         label_group = self._group_handler.get_group(name, create_mode=True)
 
-        _derive_label(
+        derive_label(
             store=label_group,
             ref_image=ref_image,
             name=name,
@@ -199,9 +206,9 @@ class LabelsContainer:
         return self.get(name)
 
 
-def _derive_label(
+def derive_label(
     store: StoreOrGroup,
-    ref_image: Image,
+    ref_image: Image | Label,
     name: str,
     shape: Collection[int] | None = None,
     pixel_size: PixelSize | None = None,
@@ -214,7 +221,8 @@ def _derive_label(
 
     Args:
         store (StoreOrGroup): The Zarr store or group to create the image in.
-        ref_image (Image): The reference image.
+        ref_image (Image | Label): A reference image that will be used to
+            create the new image.
         name (str): The name of the new image.
         shape (Collection[int] | None): The shape of the new image.
         pixel_size (PixelSize | None): The pixel size of the new image.

ngio/images/ome_zarr_container.py

@@ -502,7 +502,7 @@ class OmeZarrContainer:
     def derive_label(
         self,
         name: str,
-        ref_image: Image | None = None,
+        ref_image: Image | Label | None = None,
         shape: Collection[int] | None = None,
         pixel_size: PixelSize | None = None,
         axes_names: Collection[str] | None = None,
@@ -515,9 +515,9 @@ class OmeZarrContainer:
         And add the label to the /labels group.
 
         Args:
-            store (StoreOrGroup): The Zarr store or group to create the image in.
-            ref_image (Image): The reference image.
             name (str): The name of the new image.
+            ref_image (Image | Label | None): A reference image that will be used
+                to create the new image.
             shape (Collection[int] | None): The shape of the new image.
             pixel_size (PixelSize | None): The pixel size of the new image.
             axes_names (Collection[str] | None): The axes names of the new image.
@@ -605,7 +605,6 @@ def create_empty_ome_zarr(
     dtype: str = "uint16",
     channel_labels: list[str] | None = None,
     channel_wavelengths: list[str] | None = None,
-    percentiles: tuple[float, float] | None = None,
     channel_colors: Collection[str] | None = None,
     channel_active: Collection[bool] | None = None,
     overwrite: bool = False,
@@ -640,8 +639,6 @@ def create_empty_ome_zarr(
             Defaults to None.
         channel_wavelengths (list[str] | None, optional): The wavelengths of the
             channels. Defaults to None.
-        percentiles (tuple[float, float] | None, optional): The percentiles of the
-            channels. Defaults to None.
         channel_colors (Collection[str] | None, optional): The colors of the channels.
             Defaults to None.
         channel_active (Collection[bool] | None, optional): Whether the channels are
@@ -674,7 +671,7 @@ def create_empty_ome_zarr(
     ome_zarr.set_channel_meta(
         labels=channel_labels,
         wavelength_id=channel_wavelengths,
-        percentiles=percentiles,
+        percentiles=None,
         colors=channel_colors,
         active=channel_active,
     )

ngio/tables/_validators.py

@@ -2,9 +2,8 @@ from collections.abc import Iterable
 from typing import Protocol
 
 import pandas as pd
-import pandas.api.types as ptypes
 
-from ngio.utils import NgioTableValidationError, NgioValueError
+from ngio.utils import NgioTableValidationError
 
 
 class TableValidator(Protocol):
@@ -56,87 +55,6 @@ def validate_table(
 # Common table validators
 #
 ####################################################################################################
-def validate_index_key(
-    dataframe: pd.DataFrame, index_key: str | None, overwrite: bool = False
-) -> pd.DataFrame:
-    """Correctly set the index of the DataFrame.
-
-    This function checks if the index_key is present in the DataFrame.
-    If not it tries to set sensible defaults.
-
-    In order:
-        - If index_key is None, nothing can be done.
-        - If index_key is already the index of the DataFrame, nothing is done.
-        - If index_key is in the columns, we set the index to that column.
-        - If current index is None, we set the index to the index_key.
-        - If current index is not None and overwrite is True,
-            we set the index to the index_key.
-
-    """
-    if index_key is None:
-        # Nothing to do
-        return dataframe
-
-    if dataframe.index.name == index_key:
-        # Index is already set to index_key correctly
-        return dataframe
-
-    if index_key in dataframe.columns:
-        dataframe = dataframe.set_index(index_key)
-        return dataframe
-
-    if dataframe.index.name is None:
-        dataframe.index.name = index_key
-        return dataframe
-
-    elif overwrite:
-        dataframe.index.name = index_key
-        return dataframe
-    else:
-        raise NgioTableValidationError(
-            f"Index key {index_key} not found in DataFrame. "
-            f"Current index is {dataframe.index.name}. If you want to overwrite the "
-            "index set overwrite=True."
-        )
-
-
-def validate_index_dtype(dataframe: pd.DataFrame, index_type: str) -> pd.DataFrame:
-    """Check if the index of the DataFrame has the correct dtype."""
-    match index_type:
-        case "str":
-            if ptypes.is_integer_dtype(dataframe.index):
-                # Convert the int index to string is generally safe
-                dataframe = dataframe.set_index(dataframe.index.astype(str))
-
-            if not ptypes.is_string_dtype(dataframe.index):
-                raise NgioTableValidationError(
-                    f"Table index must be of string type, got {dataframe.index.dtype}"
-                )
-
-        case "int":
-            if ptypes.is_string_dtype(dataframe.index):
-                # Try to convert the string index to int
-                try:
-                    dataframe = dataframe.set_index(dataframe.index.astype(int))
-                except ValueError as e:
-                    if "invalid literal for int() with base 10" in str(e):
-                        raise NgioTableValidationError(
-                            "Table index must be of integer type, got str."
-                            f" We tried implicit conversion and failed: {e}"
-                        ) from None
-                    else:
-                        raise e from e
-
-            if not ptypes.is_integer_dtype(dataframe.index):
-                raise NgioTableValidationError(
-                    f"Table index must be of integer type, got {dataframe.index.dtype}"
-                )
-        case _:
-            raise NgioValueError(f"index_type {index_type} not recognized")
-
-    return dataframe
-
-
 def validate_columns(
     table_df: pd.DataFrame,
     required_columns: list[str],

ngio/tables/backends/__init__.py

@@ -1,8 +1,34 @@
 """Ngio Tables backend implementations."""
 
+from ngio.tables.backends._abstract_backend import AbstractTableBackend, BackendMeta
 from ngio.tables.backends._table_backends import (
     ImplementedTableBackends,
     TableBackendProtocol,
 )
+from ngio.tables.backends._utils import (
+    convert_anndata_to_pandas,
+    convert_anndata_to_polars,
+    convert_pandas_to_anndata,
+    convert_pandas_to_polars,
+    convert_polars_to_anndata,
+    convert_polars_to_pandas,
+    normalize_anndata,
+    normalize_pandas_df,
+    normalize_polars_lf,
+)
 
-__all__ = ["ImplementedTableBackends", "TableBackendProtocol"]
+__all__ = [
+    "AbstractTableBackend",
+    "BackendMeta",
+    "ImplementedTableBackends",
+    "TableBackendProtocol",
+    "convert_anndata_to_pandas",
+    "convert_anndata_to_polars",
+    "convert_pandas_to_anndata",
+    "convert_pandas_to_polars",
+    "convert_polars_to_anndata",
+    "convert_polars_to_pandas",
+    "normalize_anndata",
+    "normalize_pandas_df",
+    "normalize_polars_lf",
+]