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

ngio/tables/{tables_container.py → _tables_container.py}

@@ -1,10 +1,24 @@
 """Module for handling the /tables group in an OME-NGFF file."""
 
-from typing import Literal, Protocol
+from typing import Literal, Protocol, TypeVar
 
-from ngio.tables.v1 import FeatureTableV1, MaskingRoiTableV1, RoiTableV1
-from ngio.tables.v1._generic_table import GenericTable
-from ngio.tables.v1._roi_table import _GenericRoiTableV1
+import anndata as ad
+import pandas as pd
+import polars as pl
+
+from ngio.tables.backends import (
+    BackendMeta,
+    TableBackend,
+    TabularData,
+)
+from ngio.tables.v1 import (
+    ConditionTableV1,
+    FeatureTableV1,
+    GenericTable,
+    MaskingRoiTableV1,
+    RoiTableV1,
+)
+from ngio.tables.v1._roi_table import GenericRoiTableV1
 from ngio.utils import (
     AccessModeLiteral,
     NgioValidationError,
@@ -13,22 +27,23 @@ from ngio.utils import (
     ZarrGroupHandler,
 )
 
-GenericRoiTable = _GenericRoiTableV1
+GenericRoiTable = GenericRoiTableV1
 RoiTable = RoiTableV1
 MaskingRoiTable = MaskingRoiTableV1
 FeatureTable = FeatureTableV1
+ConditionTable = ConditionTableV1
 
 
 class Table(Protocol):
     """Placeholder class for a table."""
 
     @staticmethod
-    def type() -> str | None:
+    def table_type() -> str:
         """Return the type of the table."""
         ...
 
     @staticmethod
-    def version() -> str | None:
+    def version() -> str:
         """Return the version of the table."""
         ...
 
@@ -37,19 +52,72 @@ class Table(Protocol):
         """The name of the backend."""
         ...
 
+    @property
+    def meta(self) -> BackendMeta:
+        """Return the metadata for the table."""
+        ...
+
+    @property
+    def dataframe(self) -> pd.DataFrame:
+        """Return the table as a DataFrame."""
+        ...
+
+    @property
+    def lazy_frame(self) -> pl.LazyFrame:
+        """Return the table as a LazyFrame."""
+        ...
+
+    @property
+    def anndata(self) -> ad.AnnData:
+        """Return the table as an AnnData object."""
+        ...
+
+    def set_table_data(
+        self,
+        table_data: TabularData | None = None,
+        refresh: bool = False,
+    ) -> None:
+        """Make sure that the table data is set (exist in memory).
+
+        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.
+        """
+        ...
+
+    def set_backend(
+        self,
+        handler: ZarrGroupHandler | None = None,
+        backend: TableBackend = "anndata",
+    ) -> None:
+        """Set the backend store and path for the table.
+
+        Either a handler or a backend must be provided.
+
+        If the hanlder in none it will be inferred from the backend.
+        If the backend is none, it will be inferred from the group attrs
+        """
+        ...
+
     @classmethod
-    def _from_handler(
-        cls, handler: ZarrGroupHandler, backend_name: str | None = None
+    def from_handler(
+        cls,
+        handler: ZarrGroupHandler,
+        backend: TableBackend | None = None,
     ) -> "Table":
         """Create a new table from a Zarr group handler."""
         ...
 
-    def _set_backend(
-        self,
-        handler: ZarrGroupHandler,
-        backend_name: str | None = None,
-    ) -> None:
-        """Set the backend store and path for the table."""
+    @classmethod
+    def from_table_data(cls, table_data: TabularData, meta: BackendMeta) -> "Table":
+        """Create a new table from a DataFrame."""
+        ...
+
+    @property
+    def table_data(self) -> TabularData:
+        """Return the table."""
         ...
 
     def consolidate(self) -> None:
@@ -58,13 +126,37 @@ class Table(Protocol):
 
 
 TypedTable = Literal[
-    "roi_table", "masking_roi_table", "feature_table", "generic_roi_table"
+    "generic_table",
+    "roi_table",
+    "masking_roi_table",
+    "feature_table",
+    "condition_table",
 ]
 
+TypedRoiTable = Literal[
+    "roi_table",
+    "masking_roi_table",
+]
+
+TableType = TypeVar("TableType", bound=Table)
+
+
+class TableMeta(BackendMeta):
+    """Base class for table metadata."""
+
+    table_version: str = "1"
+    type: str = "generic_table"
 
-def _unique_table_name(type_name, version) -> str:
-    """Return the unique name for a table."""
-    return f"{type_name}_v{version}"
+    def unique_name(self) -> str:
+        """Return the unique name for the table."""
+        return f"{self.type}_v{self.table_version}"
+
+
+def _get_meta(handler: ZarrGroupHandler) -> TableMeta:
+    """Get the metadata from the handler."""
+    attrs = handler.load_attrs()
+    meta = TableMeta(**attrs)
+    return meta
 
 
 class ImplementedTables:
@@ -86,77 +178,38 @@ class ImplementedTables:
 
     def get_table(
         self,
-        type: str,
-        version: str,
+        meta: TableMeta,
         handler: ZarrGroupHandler,
-        backend_name: str | None = None,
+        backend: TableBackend | None = None,
         strict: bool = True,
     ) -> Table:
         """Try to get a handler for the given store based on the metadata version."""
-        _errors = {}
-        for name, table_cls in self._implemented_tables.items():
-            if name != _unique_table_name(type, version):
-                continue
-            try:
-                table = table_cls._from_handler(
-                    handler=handler, backend_name=backend_name
-                )
-                return table
-            except Exception as e:
-                if strict:
-                    raise NgioValidationError(
-                        f"Could not load table {name} from handler. Error: {e}"
-                    ) from e
-                else:
-                    _errors[name] = e
-        # If no table was found, we can try to load the table from a generic table
-        try:
-            table = GenericTable._from_handler(
-                handler=handler, backend_name=backend_name
-            )
-            return table
-        except Exception as e:
-            _errors["generic"] = e
+        if strict:
+            default = None
+        else:
+            default = GenericTable
 
-        if len(_errors) == 0:
-            raise NgioValidationError(
-                f"Could not find a table implementation for {type} v{version}. "
-                f"Available tables: {self.available_implementations()}"
+        table_cls = self._implemented_tables.get(meta.unique_name(), default)
+        if table_cls is None:
+            raise NgioValueError(
+                f"Table handler for {meta.unique_name()} not implemented."
             )
-
-        raise NgioValidationError(
-            f"Could not load table from any known version. Errors: {_errors}"
-        )
+        table = table_cls.from_handler(handler=handler, backend=backend)
+        return table
 
     def add_implementation(self, handler: type[Table], overwrite: bool = False):
         """Register a new table handler."""
-        table_type = handler.type()
-        version = handler.version()
-        if table_type is None:
-            raise NgioValueError("Table handler must have a type.")
-
-        if version is None:
-            raise NgioValueError("Table handler must have a version.")
+        meta = TableMeta(
+            type=handler.table_type(),
+            table_version=handler.version(),
+        )
 
-        table_unique_name = _unique_table_name(table_type, version)
-        if table_unique_name in self._implemented_tables and not overwrite:
+        if meta.unique_name() in self._implemented_tables and not overwrite:
             raise NgioValueError(
-                f"Table handler for {table_unique_name} already exists. "
+                f"Table handler for {meta.unique_name()} already implemented. "
                 "Use overwrite=True to replace it."
             )
-        self._implemented_tables[table_unique_name] = handler
-
-
-def _get_table_type(handler: ZarrGroupHandler) -> str:
-    """Get the type of the table from the handler."""
-    attrs = handler.load_attrs()
-    return attrs.get("type", "None")
-
-
-def _get_table_version(handler: ZarrGroupHandler) -> str:
-    """Get the version of the table from the handler."""
-    attrs = handler.load_attrs()
-    return attrs.get("fractal_table_version", "None")
+        self._implemented_tables[meta.unique_name()] = handler
 
 
 class TablesContainer:
@@ -192,14 +245,7 @@ class TablesContainer:
         handler = self._group_handler.derive_handler(path=name)
         return handler
 
-    def list_roi_tables(self) -> list[str]:
-        """List all ROI tables in the group."""
-        _tables = []
-        for _type in ["roi_table", "masking_roi_table"]:
-            _tables.extend(self.list(_type))
-        return _tables
-
-    def list(self, filter_types: str | None = None) -> list[str]:
+    def list(self, filter_types: TypedTable | str | None = None) -> list[str]:
         """List all labels in the group."""
         tables = self._get_tables_list()
         if filter_types is None:
@@ -208,34 +254,52 @@ class TablesContainer:
         filtered_tables = []
         for table_name in tables:
             tb_handler = self._get_table_group_handler(table_name)
-            table_type = _get_table_type(tb_handler)
+            table_type = _get_meta(tb_handler).type
             if table_type == filter_types:
                 filtered_tables.append(table_name)
         return filtered_tables
 
     def get(
-        self, name: str, backend_name: str | None = None, strict: bool = True
+        self,
+        name: str,
+        backend: TableBackend | None = None,
+        strict: bool = True,
     ) -> Table:
         """Get a label from the group."""
         if name not in self.list():
-            raise KeyError(f"Table '{name}' not found in the group.")
+            raise NgioValueError(f"Table '{name}' not found in the group.")
 
         table_handler = self._get_table_group_handler(name)
-        table_type = _get_table_type(table_handler)
-        table_version = _get_table_version(table_handler)
+
+        meta = _get_meta(table_handler)
         return ImplementedTables().get_table(
-            type=table_type,
-            version=table_version,
+            meta=meta,
             handler=table_handler,
-            backend_name=backend_name,
+            backend=backend,
             strict=strict,
         )
 
+    def get_as(
+        self,
+        name: str,
+        table_cls: type[TableType],
+        backend: TableBackend | None = None,
+    ) -> TableType:
+        """Get a table from the group as a specific type."""
+        if name not in self.list():
+            raise NgioValueError(f"Table '{name}' not found in the group.")
+
+        table_handler = self._get_table_group_handler(name)
+        return table_cls.from_handler(
+            handler=table_handler,
+            backend=backend,
+        )  # type: ignore[return-value]
+
     def add(
         self,
         name: str,
         table: Table,
-        backend: str | None = None,
+        backend: TableBackend = "anndata",
         overwrite: bool = False,
     ) -> None:
         """Add a table to the group."""
@@ -253,9 +317,10 @@ class TablesContainer:
         if backend is None:
             backend = table.backend_name
 
-        table._set_backend(
+        table.set_table_data()
+        table.set_backend(
             handler=table_handler,
-            backend_name=backend,
+            backend=backend,
         )
         table.consolidate()
         if name not in existing_tables:
@@ -266,6 +331,7 @@ class TablesContainer:
 ImplementedTables().add_implementation(RoiTableV1)
 ImplementedTables().add_implementation(MaskingRoiTableV1)
 ImplementedTables().add_implementation(FeatureTableV1)
+ImplementedTables().add_implementation(ConditionTableV1)
 
 ###################################################################################
 #
@@ -289,6 +355,7 @@ def open_tables_container(
 
 def open_table(
     store: StoreOrGroup,
+    backend: TableBackend | None = None,
     cache: bool = False,
     mode: AccessModeLiteral = "a",
     parallel_safe: bool = False,
@@ -297,15 +364,34 @@ def open_table(
     handler = ZarrGroupHandler(
         store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
     )
+    meta = _get_meta(handler)
     return ImplementedTables().get_table(
-        _get_table_type(handler), _get_table_version(handler), handler
+        meta=meta, handler=handler, backend=backend, strict=False
     )
 
 
+def open_table_as(
+    store: StoreOrGroup,
+    table_cls: type[TableType],
+    backend: TableBackend | None = None,
+    cache: bool = False,
+    mode: AccessModeLiteral = "a",
+    parallel_safe: bool = False,
+) -> TableType:
+    """Open a table from a Zarr store as a specific type."""
+    handler = ZarrGroupHandler(
+        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
+    )
+    return table_cls.from_handler(
+        handler=handler,
+        backend=backend,
+    )  # type: ignore[return-value]
+
+
 def write_table(
     store: StoreOrGroup,
     table: Table,
-    backend: str | None = None,
+    backend: TableBackend = "anndata",
     cache: bool = False,
     mode: AccessModeLiteral = "a",
     parallel_safe: bool = False,
@@ -314,8 +400,8 @@ def write_table(
     handler = ZarrGroupHandler(
         store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
     )
-    table._set_backend(
+    table.set_backend(
         handler=handler,
-        backend_name=backend,
+        backend=backend,
     )
     table.consolidate()

ngio/tables/backends/__init__.py

@@ -1,34 +1,54 @@
 """Ngio Tables backend implementations."""
 
 from ngio.tables.backends._abstract_backend import AbstractTableBackend, BackendMeta
+from ngio.tables.backends._anndata import AnnDataBackend
+from ngio.tables.backends._csv import CsvTableBackend
+from ngio.tables.backends._json import JsonTableBackend
+from ngio.tables.backends._parquet import ParquetTableBackend
 from ngio.tables.backends._table_backends import (
     ImplementedTableBackends,
+    TableBackend,
     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",
+    "TableBackend",
     "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",
 ]