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

ngio/tables/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,32 @@ class Table(Protocol):
 
 
 TypedTable = Literal[
-    "roi_table", "masking_roi_table", "feature_table", "generic_roi_table"
+    "roi_table",
+    "masking_roi_table",
+    "feature_table",
+    "generic_roi_table",
+    "condition_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 +173,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:
@@ -208,34 +256,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 +319,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 +333,7 @@ class TablesContainer:
 ImplementedTables().add_implementation(RoiTableV1)
 ImplementedTables().add_implementation(MaskingRoiTableV1)
 ImplementedTables().add_implementation(FeatureTableV1)
+ImplementedTables().add_implementation(ConditionTableV1)
 
 ###################################################################################
 #
@@ -289,6 +357,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 +366,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 +402,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/v1/__init__.py

@@ -1,7 +1,23 @@
 """Tables implementations for fractal_tables v1."""
 
-from ngio.tables.v1._feature_table import FeatureTableV1
+from ngio.tables.v1._condition_table import ConditionTableMeta, ConditionTableV1
+from ngio.tables.v1._feature_table import FeatureTableMeta, FeatureTableV1
 from ngio.tables.v1._generic_table import GenericTable
-from ngio.tables.v1._roi_table import MaskingRoiTableV1, RoiTableV1
+from ngio.tables.v1._roi_table import (
+    MaskingRoiTableV1,
+    MaskingRoiTableV1Meta,
+    RoiTableV1,
+    RoiTableV1Meta,
+)
 
-__all__ = ["FeatureTableV1", "GenericTable", "MaskingRoiTableV1", "RoiTableV1"]
+__all__ = [
+    "ConditionTableMeta",
+    "ConditionTableV1",
+    "FeatureTableMeta",
+    "FeatureTableV1",
+    "GenericTable",
+    "MaskingRoiTableV1",
+    "MaskingRoiTableV1Meta",
+    "RoiTableV1",
+    "RoiTableV1Meta",
+]

ngio/tables/v1/_condition_table.py

@@ -0,0 +1,71 @@
+"""Implementation of a generic table class."""
+
+from ngio.tables.abstract_table import AbstractBaseTable
+from ngio.tables.backends import (
+    BackendMeta,
+    TableBackend,
+    TabularData,
+)
+from ngio.utils import ZarrGroupHandler
+
+
+class ConditionTableMeta(BackendMeta):
+    """Metadata for the condition table."""
+
+    table_version: str | None = "1"
+    type: str | None = "condition_table"
+
+
+class ConditionTableV1(AbstractBaseTable):
+    """Condition table class.
+
+    This class is used to load a condition table.
+    The condition table is a generic table that does not
+    have a specific definition.
+
+    It is used to store informations about the particular conditions
+    used to generate the data.
+    - How much drug was used in the experiment
+    - What treatment was used
+    - etc.
+    """
+
+    def __init__(
+        self,
+        table_data: TabularData | None = None,
+        *,
+        meta: ConditionTableMeta | None = None,
+    ) -> None:
+        """Initialize the ConditionTable."""
+        if meta is None:
+            meta = ConditionTableMeta()
+
+        super().__init__(
+            table_data=table_data,
+            meta=meta,
+        )
+
+    @staticmethod
+    def table_type() -> str:
+        """Return the type of the table."""
+        return "condition_table"
+
+    @staticmethod
+    def version() -> str:
+        """The generic table does not have a version.
+
+        Since does not follow a specific schema.
+        """
+        return "1"
+
+    @classmethod
+    def from_handler(
+        cls,
+        handler: ZarrGroupHandler,
+        backend: TableBackend | None = None,
+    ) -> "ConditionTableV1":
+        return cls._from_handler(
+            handler=handler,
+            backend=backend,
+            meta_model=ConditionTableMeta,
+        )