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

ngio/tables/backends/_utils.py

@@ -9,7 +9,6 @@ These functions are used to validate and normalize the tables
 to ensure that conversion between formats is consistent.
 """
 
-# %%
 from copy import deepcopy
 from typing import Literal
 
@@ -24,6 +23,8 @@ from polars import LazyFrame
 
 from ngio.utils import NgioTableValidationError, NgioValueError
 
+TabularData = AnnData | DataFrame | PolarsDataFrame | LazyFrame
+
 # -----------------
 # Validation utils
 # -----------------
@@ -460,3 +461,148 @@ def convert_polars_to_anndata(
         pandas_df,
         index_key=index_key,
     )
+
+
+# -----------------
+# Conversion functions
+# -----------------
+
+
+def normalize_table(
+    table_data: TabularData,
+    index_key: str | None = None,
+    index_type: Literal["int", "str"] | None = None,
+) -> TabularData:
+    """Normalize a table to a specific format.
+
+    Args:
+        table_data (TabularData): The table to normalize.
+        index_key (str | None): The column name to use as the index of the DataFrame.
+            Default is None.
+        index_type (str | None): The type of the index column in the DataFrame.
+            Either 'str' or 'int'. Default is None.
+
+    Returns:
+        DataFrame | AnnData | PolarsDataFrame | LazyFrame: Normalized table.
+    """
+    if isinstance(table_data, DataFrame):
+        return normalize_pandas_df(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+            reset_index=False,
+        )
+    if isinstance(table_data, AnnData):
+        return normalize_anndata(table_data, index_key=index_key)
+    if isinstance(table_data, PolarsDataFrame) or isinstance(table_data, LazyFrame):
+        return normalize_polars_lf(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+        )
+    raise NgioValueError(f"Unsupported table type: {type(table_data)}")
+
+
+def convert_to_anndata(
+    table_data: TabularData,
+    index_key: str | None = None,
+) -> AnnData:
+    """Convert a table to an AnnData object.
+
+    Args:
+        table_data (TabularData): The table to convert.
+        index_key (str | None): The column name to use as the index of the DataFrame.
+            Default is None.
+
+    Returns:
+        AnnData: Converted AnnData object.
+    """
+    if isinstance(table_data, AnnData):
+        return normalize_anndata(table_data, index_key=index_key)
+    if isinstance(table_data, DataFrame):
+        return convert_pandas_to_anndata(table_data, index_key=index_key)
+    if isinstance(table_data, PolarsDataFrame) or isinstance(table_data, LazyFrame):
+        return convert_polars_to_anndata(table_data, index_key=index_key)
+    raise NgioValueError(f"Unsupported table type: {type(table_data)}")
+
+
+def convert_to_pandas(
+    table_data: TabularData,
+    index_key: str | None = None,
+    index_type: Literal["int", "str"] | None = None,
+    reset_index: bool = False,
+) -> DataFrame:
+    """Convert a table to a pandas DataFrame.
+
+    Args:
+        table_data (TabularData): The table to convert.
+        index_key (str | None): The column name to use as the index of the DataFrame.
+            Default is None.
+        index_type (str | None): The type of the index column in the DataFrame.
+            Either 'str' or 'int'. Default is None.
+        reset_index (bool): If True the index will be reset (i.e., the index will be
+            converted to a column). If False, the index will be kept as is.
+
+    Returns:
+        DataFrame: Converted pandas DataFrame.
+    """
+    if isinstance(table_data, DataFrame):
+        return normalize_pandas_df(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+            reset_index=reset_index,
+        )
+    if isinstance(table_data, AnnData):
+        return convert_anndata_to_pandas(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+            reset_index=reset_index,
+        )
+    if isinstance(table_data, PolarsDataFrame) or isinstance(table_data, LazyFrame):
+        return convert_polars_to_pandas(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+            reset_index=reset_index,
+        )
+    raise NgioValueError(f"Unsupported table type: {type(table_data)}")
+
+
+def convert_to_polars(
+    table_data: TabularData,
+    index_key: str | None = None,
+    index_type: Literal["int", "str"] | None = None,
+) -> LazyFrame:
+    """Convert a table to a polars LazyFrame.
+
+    Args:
+        table_data (TabularData): The table to convert.
+        index_key (str | None): The column name to use as the index of the DataFrame.
+            Default is None.
+        index_type (str | None): The type of the index column in the DataFrame.
+            Either 'str' or 'int'. Default is None.
+
+    Returns:
+        LazyFrame: Converted polars LazyFrame.
+    """
+    if isinstance(table_data, PolarsDataFrame) or isinstance(table_data, LazyFrame):
+        return normalize_polars_lf(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+        )
+    if isinstance(table_data, DataFrame):
+        return convert_pandas_to_polars(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+        )
+    if isinstance(table_data, AnnData):
+        return convert_anndata_to_polars(
+            table_data,
+            index_key=index_key,
+            index_type=index_type,
+        )
+    raise NgioValueError(f"Unsupported table type: {type(table_data)}")

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,
+        )

ngio/tables/v1/_feature_table.py

@@ -6,12 +6,12 @@ https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
 
 from typing import Literal
 
-import pandas as pd
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
-from ngio.tables.backends import BackendMeta, ImplementedTableBackends
-from ngio.tables.backends._utils import normalize_pandas_df
-from ngio.utils import NgioValueError, ZarrGroupHandler
+from ngio.tables._abstract_table import AbstractBaseTable
+from ngio.tables.backends import BackendMeta, TableBackend, TabularData
+from ngio.utils import NgioValueError
+from ngio.utils._zarr_utils import ZarrGroupHandler
 
 
 class RegionMeta(BaseModel):
@@ -23,42 +23,52 @@ class RegionMeta(BaseModel):
 class FeatureTableMeta(BackendMeta):
     """Metadata for the ROI table."""
 
-    fractal_table_version: Literal["1"] = "1"
+    table_version: Literal["1"] = "1"
     type: Literal["feature_table"] = "feature_table"
     region: RegionMeta | None = None
-    instance_key: str = "label"
+    instance_key: str = "label"  # Legacy field, kept for compatibility
+    # Backend metadata
+    index_key: str | None = "label"
+    index_type: Literal["int", "str"] | None = "int"
+    # Columns optional types
+    categorical_columns: list[str] = Field(default_factory=list)
+    measurement_columns: list[str] = Field(default_factory=list)
+    metadata_columns: list[str] = Field(default_factory=list)
 
 
-class FeatureTableV1:
-    """Class to represent a feature table.
-
-    This can be used to load any table that does not have
-    a specific definition.
-    """
-
+class FeatureTableV1(AbstractBaseTable):
     def __init__(
         self,
-        dataframe: pd.DataFrame | None = None,
+        table_data: TabularData | None = None,
+        *,
         reference_label: str | None = None,
+        meta: FeatureTableMeta | None = None,
     ) -> None:
         """Initialize the GenericTable."""
-        if reference_label is None:
-            self._meta = FeatureTableMeta()
-        else:
+        if meta is None:
+            meta = FeatureTableMeta()
+
+        if reference_label is not None:
             path = f"../labels/{reference_label}"
-            self._meta = FeatureTableMeta(region=RegionMeta(path=path))
-
-        self._instance_key = "label"
-        if dataframe is None:
-            self._dataframe = None
-        else:
-            self._dataframe = normalize_pandas_df(
-                dataframe,
-                index_key=self._instance_key,
-                index_type="int",
-                reset_index=False,
+            meta = FeatureTableMeta(region=RegionMeta(path=path))
+
+        if table_data is not None and not isinstance(table_data, TabularData):
+            raise NgioValueError(
+                f"The table is not of type SupportedTables. Got {type(table_data)}"
             )
-        self._table_backend = None
+
+        if meta.index_key is None:
+            meta.index_key = "label"
+
+        if meta.index_type is None:
+            meta.index_type = "int"
+
+        meta.instance_key = meta.index_key
+
+        super().__init__(
+            table_data=table_data,
+            meta=meta,
+        )
 
     def __repr__(self) -> str:
         """Return a string representation of the table."""
@@ -69,8 +79,29 @@ class FeatureTableV1:
             properties += f", reference_label={self.reference_label}"
         return f"FeatureTableV1({properties})"
 
+    @classmethod
+    def from_handler(
+        cls,
+        handler: ZarrGroupHandler,
+        backend: TableBackend | None = None,
+    ) -> "FeatureTableV1":
+        return cls._from_handler(
+            handler=handler,
+            backend=backend,
+            meta_model=FeatureTableMeta,
+        )
+
+    @property
+    def meta(self) -> FeatureTableMeta:
+        """Return the metadata of the table."""
+        if not isinstance(self._meta, FeatureTableMeta):
+            raise NgioValueError(
+                "The metadata of the table is not of type FeatureTableMeta."
+            )
+        return self._meta
+
     @staticmethod
-    def type() -> str:
+    def table_type() -> str:
         """Return the type of the table."""
         return "feature_table"
 
@@ -82,110 +113,13 @@ class FeatureTableV1:
         """
         return "1"
 
-    @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 reference_label(self) -> str | None:
         """Return the reference label."""
-        path = self._meta.region
+        path = self.meta.region
         if path is None:
             return None
 
         path = path.path
         path = path.split("/")[-1]
         return path
-
-    @property
-    def dataframe(self) -> pd.DataFrame:
-        """Return the table as a DataFrame."""
-        if self._dataframe is None and self._table_backend is None:
-            raise NgioValueError(
-                "The table does not have a DataFrame in memory nor a backend."
-            )
-
-        if self._dataframe is None and self._table_backend is not None:
-            self._dataframe = self._table_backend.load_as_pandas_df()
-
-        if self._dataframe is None:
-            raise NgioValueError(
-                "The table does not have a DataFrame in memory nor a backend."
-            )
-        return self._dataframe
-
-    @dataframe.setter
-    def dataframe(self, dataframe: pd.DataFrame) -> None:
-        """Set the table as a DataFrame."""
-        self._dataframe = normalize_pandas_df(
-            dataframe,
-            index_key=self._instance_key,
-            index_type="int",
-            reset_index=False,
-        )
-
-    @classmethod
-    def _from_handler(
-        cls, handler: ZarrGroupHandler, backend_name: str | None = None
-    ) -> "FeatureTableV1":
-        """Create a new ROI table from a Zarr group handler."""
-        meta = FeatureTableMeta(**handler.load_attrs())
-        instance_key = "label" if meta.instance_key is None else meta.instance_key
-        if backend_name is None:
-            backend = ImplementedTableBackends().get_backend(
-                backend_name=meta.backend,
-                group_handler=handler,
-                index_key=instance_key,
-                index_type="int",
-            )
-        else:
-            backend = ImplementedTableBackends().get_backend(
-                backend_name=backend_name,
-                group_handler=handler,
-                index_key=instance_key,
-                index_type="int",
-            )
-            meta.backend = backend_name
-
-        if not backend.implements_pandas:
-            raise NgioValueError(
-                "The backend does not implement the dataframe protocol."
-            )
-
-        table = cls()
-        table._meta = meta
-        table._table_backend = backend
-        return table
-
-    def _set_backend(
-        self,
-        handler: ZarrGroupHandler,
-        backend_name: str | None = None,
-    ) -> None:
-        """Set the backend of the table."""
-        instance_key = "label" if self._instance_key is None else self._instance_key
-        backend = ImplementedTableBackends().get_backend(
-            backend_name=backend_name,
-            group_handler=handler,
-            index_key=instance_key,
-            index_type="int",
-        )
-        self._meta.backend = backend_name
-        self._table_backend = backend
-
-    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.dataframe,
-            metadata=self._meta.model_dump(exclude_none=True),
-            mode="pandas",
-        )