ngio 0.2.7__py3-none-any.whl → 0.3.0a0__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,
+    TableBackendProtocol,
     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: str | TableBackendProtocol | 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 (str | TableBackendProtocol | 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: str | TableBackendProtocol = "anndata_v1",
         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/ngio_specs/_channels.py

@@ -9,7 +9,7 @@ from enum import Enum
 from typing import Any, TypeVar
 
 import numpy as np
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
 
 from ngio.utils import NgioValidationError, NgioValueError
 
@@ -124,7 +124,6 @@ class ChannelVisualisation(BaseModel):
     model_config = ConfigDict(extra="allow", frozen=True)
 
     @field_validator("color", mode="after")
-    @classmethod
     def validate_color(cls, value: str | NgioColors) -> str:
         """Color validator.
 
@@ -145,6 +144,33 @@ class ChannelVisualisation(BaseModel):
         else:
             raise NgioValueError(f"Invalid color {value}.")
 
+    @model_validator(mode="before")
+    def check_start_end(cls, data):
+        """Check that the start and end values are valid.
+
+        If the start and end values are equal, set the end value to start + 1
+        """
+        start = data.get("start", None)
+        end = data.get("end", None)
+        if start is None or end is None:
+            return data
+        if abs(end - start) < 1e-6:
+            data["end"] = start + 1
+        return data
+
+    @model_validator(mode="after")
+    def check_model(self) -> "ChannelVisualisation":
+        """Check that the start and end values are within the min and max values."""
+        if self.start < self.min or self.start > self.max:
+            raise NgioValidationError(
+                f"Start value {self.start} is out of range [{self.min}, {self.max}]"
+            )
+        if self.end < self.min or self.end > self.max:
+            raise NgioValidationError(
+                f"End value {self.end} is out of range [{self.min}, {self.max}]"
+            )
+        return self
+
     @classmethod
     def default_init(
         cls,

ngio/tables/__init__.py

@@ -1,20 +1,24 @@
 """Ngio Tables implementations."""
 
-from ngio.tables.backends import ImplementedTableBackends
+from ngio.tables.backends import ImplementedTableBackends, 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 +26,11 @@ __all__ = [
     "MaskingRoiTable",
     "RoiTable",
     "Table",
+    "TableBackendProtocol",
+    "TableType",
     "TablesContainer",
     "TypedTable",
     "open_table",
+    "open_table_as",
     "open_tables_container",
 ]

ngio/tables/abstract_table.py

@@ -0,0 +1,268 @@
+"""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,
+    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: str | TableBackendProtocol,
+    ) -> 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: str | TableBackendProtocol = "anndata_v1",
+    ) -> 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: str | TableBackendProtocol | 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: str | TableBackendProtocol | 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),
+        )

ngio/tables/backends/__init__.py

@@ -1,34 +1,52 @@
 """Ngio Tables backend implementations."""
 
 from ngio.tables.backends._abstract_backend import AbstractTableBackend, BackendMeta
+from ngio.tables.backends._anndata_v1 import AnnDataBackend
+from ngio.tables.backends._csv_v1 import CsvTableBackend
+from ngio.tables.backends._json_v1 import JsonTableBackend
+from ngio.tables.backends._parquet_v1 import ParquetTableBackend
 from ngio.tables.backends._table_backends import (
     ImplementedTableBackends,
     TableBackendProtocol,
 )
 from ngio.tables.backends._utils import (
+    TabularData,
     convert_anndata_to_pandas,
     convert_anndata_to_polars,
     convert_pandas_to_anndata,
     convert_pandas_to_polars,
     convert_polars_to_anndata,
     convert_polars_to_pandas,
+    convert_to_anndata,
+    convert_to_pandas,
+    convert_to_polars,
     normalize_anndata,
     normalize_pandas_df,
     normalize_polars_lf,
+    normalize_table,
 )
 
 __all__ = [
     "AbstractTableBackend",
+    "AnnDataBackend",
     "BackendMeta",
+    "CsvTableBackend",
     "ImplementedTableBackends",
+    "JsonTableBackend",
+    "ParquetTableBackend",
     "TableBackendProtocol",
+    "TabularData",
     "convert_anndata_to_pandas",
     "convert_anndata_to_polars",
     "convert_pandas_to_anndata",
     "convert_pandas_to_polars",
     "convert_polars_to_anndata",
     "convert_polars_to_pandas",
+    "convert_to_anndata",
+    "convert_to_pandas",
+    "convert_to_polars",
     "normalize_anndata",
     "normalize_pandas_df",
     "normalize_polars_lf",
+    "normalize_table",
 ]