ngio 0.2.9__py3-none-any.whl → 0.3.0a1__py3-none-any.whl

ngio/images/ome_zarr_container.py

@@ -1,7 +1,7 @@
 """Abstract class for handling OME-NGFF images."""
 
+import warnings
 from collections.abc import Collection
-from typing import Literal, overload
 
 import numpy as np
 
@@ -22,12 +22,15 @@ from ngio.ome_zarr_meta.ngio_specs import (
     TimeUnits,
 )
 from ngio.tables import (
+    ConditionTable,
     FeatureTable,
     GenericRoiTable,
     MaskingRoiTable,
     RoiTable,
     Table,
+    TableBackend,
     TablesContainer,
+    TableType,
     TypedTable,
 )
 from ngio.utils import (
@@ -264,9 +267,7 @@ class OmeZarrContainer:
         if masking_table_name is None:
             masking_table = masking_label.build_masking_roi_table()
         else:
-            masking_table = self.get_table(
-                masking_table_name, check_type="masking_roi_table"
-            )
+            masking_table = self.get_masking_roi_table(name=masking_table_name)
 
         return MaskedImage(
             group_handler=image._group_handler,
@@ -345,84 +346,116 @@ class OmeZarrContainer:
             )
         return new_ome_zarr
 
-    def list_tables(self) -> list[str]:
+    def list_tables(self, filter_types: str | None = None) -> list[str]:
         """List all tables in the image."""
-        return self.tables_container.list()
+        return self.tables_container.list(filter_types=filter_types)
 
     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) -> Table: ...
+    def get_roi_table(self, name: str) -> RoiTable:
+        """Get a ROI table from the image.
+
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, RoiTable):
+            raise NgioValueError(f"Table {name} is not a ROI table. Got {type(table)}")
+        return table
+
+    def get_masking_roi_table(self, name: str) -> MaskingRoiTable:
+        """Get a masking ROI table from the image.
+
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, MaskingRoiTable):
+            raise NgioValueError(
+                f"Table {name} is not a masking ROI table. Got {type(table)}"
+            )
+        return table
+
+    def get_feature_table(self, name: str) -> FeatureTable:
+        """Get a feature table from the image.
 
-    @overload
-    def get_table(self, name: str, check_type: None) -> Table: ...
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, FeatureTable):
+            raise NgioValueError(
+                f"Table {name} is not a feature table. Got {type(table)}"
+            )
+        return table
 
-    @overload
-    def get_table(self, name: str, check_type: Literal["roi_table"]) -> RoiTable: ...
+    def get_generic_roi_table(self, name: str) -> GenericRoiTable:
+        """Get a generic ROI table from the image.
 
-    @overload
-    def get_table(
-        self, name: str, check_type: Literal["masking_roi_table"]
-    ) -> MaskingRoiTable: ...
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, GenericRoiTable):
+            raise NgioValueError(
+                f"Table {name} is not a generic ROI table. Got {type(table)}"
+            )
+        return table
 
-    @overload
-    def get_table(
-        self, name: str, check_type: Literal["feature_table"]
-    ) -> FeatureTable: ...
+    def get_condition_table(self, name: str) -> ConditionTable:
+        """Get a condition table from the image.
 
-    @overload
-    def get_table(
-        self, name: str, check_type: Literal["generic_roi_table"]
-    ) -> GenericRoiTable: ...
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, ConditionTable):
+            raise NgioValueError(
+                f"Table {name} is not a condition table. Got {type(table)}"
+            )
+        return table
 
     def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
         """Get a table from the image.
 
         Args:
             name (str): The name of the table.
-            check_type (TypedTable | None): The type of the table. If None, the
-                type is not checked. If a type is provided, the table must be of that
-                type.
+            check_type (TypedTable | None): Deprecated. Please use
+                'get_table_as' instead, or one of the type specific
+                get_*table() methods.
+
+        """
+        if check_type is not None:
+            warnings.warn(
+                "The 'check_type' argument is deprecated, and will be removed in "
+                "ngio=0.3. Use 'get_table_as' instead or one of the "
+                "type specific get_*table() methods.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self.tables_container.get(name=name, strict=False)
+
+    def get_table_as(
+        self,
+        name: str,
+        table_cls: type[TableType],
+        backend: TableBackend | None = None,
+    ) -> TableType:
+        """Get a table from the image as a specific type.
+
+        Args:
+            name (str): The name of the table.
+            table_cls (type[TableType]): The type of the table.
+            backend (TableBackend | None): The backend to use. If None,
+                the default backend is used.
         """
-        if check_type is None:
-            table = self.tables_container.get(name, strict=False)
-            return table
-
-        table = self.tables_container.get(name, strict=True)
-        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 _:
-                raise NgioValueError(f"Unknown check_type: {check_type}")
+        return self.tables_container.get_as(
+            name=name,
+            table_cls=table_cls,
+            backend=backend,
+        )
 
     def build_image_roi_table(self, name: str = "image") -> RoiTable:
         """Compute the ROI table for an image."""
@@ -436,7 +469,7 @@ class OmeZarrContainer:
         self,
         name: str,
         table: Table,
-        backend: str | None = None,
+        backend: TableBackend = "anndata",
         overwrite: bool = False,
     ) -> None:
         """Add a table to the image."""
@@ -499,9 +532,7 @@ class OmeZarrContainer:
         if masking_table_name is None:
             masking_table = masking_label.build_masking_roi_table()
         else:
-            masking_table = self.get_table(
-                masking_table_name, check_type="masking_roi_table"
-            )
+            masking_table = self.get_masking_roi_table(name=masking_table_name)
 
         return MaskedLabel(
             group_handler=label._group_handler,

ngio/ome_zarr_meta/_meta_handlers.py

@@ -187,10 +187,6 @@ class GenericMetaHandler(
 
         raise NgioValueError(f"Could not load metadata: {meta_or_error}")
 
-    def safe_load_meta(self) -> _image_meta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
-
     def _write_meta(self, meta) -> None:
         """Write the metadata to the store."""
         _meta = self._meta_exporter(metadata=meta)
@@ -217,6 +213,10 @@ class ImageMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioImageMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 class LabelMetaHandler(
     GenericMetaHandler[NgioLabelMeta, LabelMetaImporter, LabelMetaExporter]
@@ -230,6 +230,10 @@ class LabelMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioLabelMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 ###########################################################################
 #
@@ -267,10 +271,6 @@ class GenericHCSMetaHandler(Generic[_hcs_meta, _hcs_meta_importer, _hcs_meta_exp
 
         raise NgioValueError(f"Could not load metadata: {meta_or_error}")
 
-    def safe_load_meta(self) -> _hcs_meta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
-
     def _write_meta(self, meta) -> None:
         _meta = self._meta_exporter(metadata=meta)
         self._group_handler.write_attrs(_meta)
@@ -295,6 +295,10 @@ class WellMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioWellMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 class PlateMetaHandler(
     GenericHCSMetaHandler[NgioPlateMeta, PlateMetaImporter, PlateMetaExporter]
@@ -308,6 +312,10 @@ class PlateMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioPlateMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 ###########################################################################
 #

ngio/ome_zarr_meta/ngio_specs/_axes.py

@@ -2,12 +2,15 @@
 
 from collections.abc import Collection
 from enum import Enum
+from logging import Logger
 from typing import Literal, TypeVar
 
 import numpy as np
 from pydantic import BaseModel, ConfigDict, Field
 
-from ngio.utils import NgioValidationError, NgioValueError, ngio_logger
+from ngio.utils import NgioValidationError, NgioValueError
+
+logger = Logger(__name__)
 
 T = TypeVar("T")
 
@@ -99,20 +102,20 @@ class Axis(BaseModel):
     def implicit_type_cast(self, cast_type: AxisType) -> "Axis":
         unit = self.unit
         if self.axis_type != cast_type:
-            ngio_logger.warning(
+            logger.warning(
                 f"Axis {self.on_disk_name} has type {self.axis_type}. "
                 f"Casting to {cast_type}."
             )
 
         if cast_type == AxisType.time and unit is None:
-            ngio_logger.warning(
+            logger.warning(
                 f"Time axis {self.on_disk_name} has unit {self.unit}. "
                 f"Casting to {DefaultSpaceUnit}."
             )
             unit = DefaultTimeUnit
 
         if cast_type == AxisType.space and unit is None:
-            ngio_logger.warning(
+            logger.warning(
                 f"Space axis {self.on_disk_name} has unit {unit}. "
                 f"Casting to {DefaultSpaceUnit}."
             )

ngio/tables/__init__.py

@@ -1,20 +1,28 @@
 """Ngio Tables implementations."""
 
-from ngio.tables.backends import ImplementedTableBackends
+from ngio.tables.backends import (
+    ImplementedTableBackends,
+    TableBackend,
+    TableBackendProtocol,
+)
 from ngio.tables.tables_container import (
+    ConditionTable,
     FeatureTable,
     GenericRoiTable,
     MaskingRoiTable,
     RoiTable,
     Table,
     TablesContainer,
+    TableType,
     TypedTable,
     open_table,
+    open_table_as,
     open_tables_container,
 )
 from ngio.tables.v1._generic_table import GenericTable
 
 __all__ = [
+    "ConditionTable",
     "FeatureTable",
     "GenericRoiTable",
     "GenericTable",
@@ -22,8 +30,12 @@ __all__ = [
     "MaskingRoiTable",
     "RoiTable",
     "Table",
+    "TableBackend",
+    "TableBackendProtocol",
+    "TableType",
     "TablesContainer",
     "TypedTable",
     "open_table",
+    "open_table_as",
     "open_tables_container",
 ]

ngio/tables/abstract_table.py

@@ -0,0 +1,269 @@
+"""Implementation of a generic table class."""
+
+import builtins
+from abc import ABC, abstractmethod
+from typing import Literal, Self
+
+import pandas as pd
+import polars as pl
+from anndata import AnnData
+
+from ngio.tables.backends import (
+    BackendMeta,
+    ImplementedTableBackends,
+    TableBackend,
+    TableBackendProtocol,
+    TabularData,
+    convert_to_anndata,
+    convert_to_pandas,
+    convert_to_polars,
+    normalize_table,
+)
+from ngio.utils import NgioValueError, ZarrGroupHandler
+
+
+class AbstractBaseTable(ABC):
+    """Abstract base class for a table.
+
+    This is used to define common methods and properties
+    for all tables.
+
+    This class is not meant to be used directly.
+    """
+
+    def __init__(
+        self,
+        table_data: TabularData | None = None,
+        *,
+        meta: BackendMeta | None = None,
+    ) -> None:
+        """Initialize the table."""
+        if meta is None:
+            meta = BackendMeta()
+
+        self._meta = meta
+        if table_data is not None:
+            table_data = normalize_table(
+                table_data,
+                index_key=meta.index_key,
+                index_type=meta.index_type,
+            )
+        self._table_data = table_data
+        self._table_backend = None
+
+    def __repr__(self) -> str:
+        """Return a string representation of the table."""
+        return f"{self.__class__.__name__}"
+
+    @staticmethod
+    @abstractmethod
+    def table_type() -> str:
+        """Return the type of the table."""
+        ...
+
+    @staticmethod
+    @abstractmethod
+    def version() -> str:
+        """The generic table does not have a version.
+
+        Since does not follow a specific schema.
+        """
+        ...
+
+    @property
+    def backend_name(self) -> str | None:
+        """Return the name of the backend."""
+        if self._table_backend is None:
+            return None
+        return self._table_backend.backend_name()
+
+    @property
+    def meta(self) -> BackendMeta:
+        """Return the metadata of the table."""
+        return self._meta
+
+    @property
+    def index_key(self) -> str | None:
+        """Get the index key."""
+        return self._meta.index_key
+
+    @property
+    def index_type(self) -> Literal["int", "str"] | None:
+        """Get the index type."""
+        return self._meta.index_type
+
+    def load_as_anndata(self) -> AnnData:
+        """Load the table as an AnnData object."""
+        if self._table_backend is None:
+            raise NgioValueError("No backend set for the table.")
+        return self._table_backend.load_as_anndata()
+
+    def load_as_pandas_df(self) -> pd.DataFrame:
+        """Load the table as a pandas DataFrame."""
+        if self._table_backend is None:
+            raise NgioValueError("No backend set for the table.")
+        return self._table_backend.load_as_pandas_df()
+
+    def load_as_polars_lf(self) -> pl.LazyFrame:
+        """Load the table as a polars LazyFrame."""
+        if self._table_backend is None:
+            raise NgioValueError("No backend set for the table.")
+        return self._table_backend.load_as_polars_lf()
+
+    @property
+    def table_data(self) -> TabularData:
+        """Return the table."""
+        if self._table_data is not None:
+            return self._table_data
+
+        if self._table_backend is None:
+            raise NgioValueError(
+                "The table does not have a DataFrame in memory nor a backend."
+            )
+
+        self._table_data = self._table_backend.load()
+        return self._table_data
+
+    @property
+    def dataframe(self) -> pd.DataFrame:
+        """Return the table as a DataFrame."""
+        return convert_to_pandas(
+            self.table_data, index_key=self.index_key, index_type=self.index_type
+        )
+
+    @property
+    def lazy_frame(self) -> pl.LazyFrame:
+        """Return the table as a LazyFrame."""
+        return convert_to_polars(
+            self.table_data, index_key=self.index_key, index_type=self.index_type
+        )
+
+    @property
+    def anndata(self) -> AnnData:
+        """Return the table as an AnnData object."""
+        return convert_to_anndata(self.table_data, index_key=self.index_key)
+
+    @staticmethod
+    def _load_backend(
+        meta: BackendMeta,
+        handler: ZarrGroupHandler,
+        backend: TableBackend,
+    ) -> TableBackendProtocol:
+        """Create a new ROI table from a Zarr group handler."""
+        if isinstance(backend, str):
+            return ImplementedTableBackends().get_backend(
+                backend_name=backend,
+                group_handler=handler,
+                index_key=meta.index_key,
+                index_type=meta.index_type,
+            )
+        backend.set_group_handler(
+            group_handler=handler,
+            index_key=meta.index_key,
+            index_type=meta.index_type,
+        )
+        return backend
+
+    def set_table_data(
+        self,
+        table_data: TabularData | None = None,
+        refresh: bool = False,
+    ) -> None:
+        """Set the table.
+
+        If an object is passed, it will be used as the table.
+        If None is passed, the table will be loaded from the backend.
+
+        If refresh is True, the table will be reloaded from the backend.
+            If table is not None, this will be ignored.
+        """
+        if table_data is not None:
+            if not isinstance(table_data, TabularData):
+                raise NgioValueError(
+                    "The table must be a pandas DataFrame, polars LazyFrame, "
+                    " or AnnData object."
+                )
+
+            self._table_data = normalize_table(
+                table_data,
+                index_key=self.index_key,
+                index_type=self.index_type,
+            )
+            return None
+
+        if self._table_data is not None and not refresh:
+            return None
+
+        if self._table_backend is None:
+            raise NgioValueError(
+                "The table does not have a DataFrame in memory nor a backend."
+            )
+        self._table_data = self._table_backend.load()
+
+    def set_backend(
+        self,
+        handler: ZarrGroupHandler | None = None,
+        backend: TableBackend = "anndata",
+    ) -> None:
+        """Set the backend of the table."""
+        if handler is None:
+            if self._table_backend is None:
+                raise NgioValueError(
+                    "No backend set for the table yet. "
+                    "A ZarrGroupHandler must be provided."
+                )
+            handler = self._table_backend.group_handler
+
+        meta = self._meta
+        _backend = self._load_backend(
+            meta=meta,
+            handler=handler,
+            backend=backend,
+        )
+        self._table_backend = _backend
+
+    @classmethod
+    def _from_handler(
+        cls,
+        handler: ZarrGroupHandler,
+        meta_model: builtins.type[BackendMeta],
+        backend: TableBackend | None = None,
+    ) -> Self:
+        """Create a new ROI table from a Zarr group handler."""
+        meta = meta_model(**handler.load_attrs())
+        table = cls(meta=meta)
+        if backend is None:
+            backend = meta.backend
+        table.set_backend(handler=handler, backend=backend)
+        return table
+
+    @classmethod
+    @abstractmethod
+    def from_handler(
+        cls,
+        handler: ZarrGroupHandler,
+        backend: TableBackend | None = None,
+    ) -> Self:
+        """Create a new ROI table from a Zarr group handler."""
+        pass
+
+    @classmethod
+    def from_table_data(cls, table_data: TabularData, meta: BackendMeta) -> Self:
+        """Create a new ROI table from a Zarr group handler."""
+        return cls(
+            table_data=table_data,
+            meta=meta,
+        )
+
+    def consolidate(self) -> None:
+        """Write the current state of the table to the Zarr file."""
+        if self._table_backend is None:
+            raise NgioValueError(
+                "No backend set for the table. "
+                "Please add the table to a OME-Zarr Image before calling consolidate."
+            )
+
+        self._table_backend.write(
+            self.table_data,
+            metadata=self._meta.model_dump(exclude_none=True),
+        )