ngio 0.1.6__py3-none-any.whl → 0.2.0a1__py3-none-any.whl

ngio/tables/v1/_generic_table.py

@@ -1,201 +1,118 @@
-"""Implementation of a Generic Table class."""
+"""Implementation of a generic table class."""
 
-from pathlib import Path
-from typing import Literal
-
-import anndata as ad
 import pandas as pd
-import zarr
 from pydantic import BaseModel
 
-from ngio.core.utils import State
-from ngio.tables._ad_reader import custom_read_zarr
-from ngio.tables._utils import Validator, table_ad_to_df, table_df_to_ad, validate_table
-
-REQUIRED_COLUMNS = [
-    "x_micrometer",
-    "y_micrometer",
-    "z_micrometer",
-    "len_x_micrometer",
-    "len_y_micrometer",
-    "len_z_micrometer",
-]
-
-
-def write_table_ad(
-    group: zarr.Group,
-    table: pd.DataFrame,
-    index_key: str,
-    index_type: Literal["int", "str"],
-    meta: BaseModel,
-    validators: list[Validator] | None = None,
-) -> None:
-    """Write a table to a Zarr group.
-
-    Args:
-        group (zarr.Group): The group to write the table to.
-        table (pd.DataFrame): The table to write.
-        index_key (str): The column name to use as the index of the DataFrame.
-        index_type (str): The type of the index column in the DataFrame.
-        meta (BaseModel): The metadata of the table.
-        validators (list[Validator]): A list of functions to further validate the
-            table.
-    """
-    ad_table = table_df_to_ad(
-        table,
-        index_key=index_key,
-        index_type=index_type,
-        validators=validators,
-    )
-
-    group_path = Path(group.store.path) / group.path
-    ad_table.write_zarr(group_path)
-    group.attrs.update(meta.model_dump(exclude=None))
+from ngio.tables.backends import ImplementedTableBackends
+from ngio.utils import ZarrGroupHandler
 
 
-class BaseTable:
-    """A base table class to be used for table operations in all other tables."""
+class GenericTableMeta(BaseModel):
+    """Metadata for the ROI table."""
 
-    def __init__(
-        self,
-        group: zarr.Group,
-        index_key: str,
-        index_type: Literal["int", "str"],
-        validators: list[Validator] | None = None,
-    ):
-        """Initialize the class from an existing group.
-
-        Args:
-            group (zarr.Group): The group containing the
-                ROI table.
-            index_key (str): The column name to use as the index of the DataFrame.
-            index_type (str): The type of the index column in the DataFrame.
-            validators (list[Validator]): A list of functions to further validate the
-                table.
-        """
-        self._table_group = group
-        self._index_key = index_key
-        self._index_type = index_type
-        self._validators = validators
-
-        table_ad = custom_read_zarr(store=group)
-
-        self._table = table_ad_to_df(
-            table_ad=table_ad,
-            index_key=self._index_key,
-            index_type=self._index_type,
-            validators=self._validators,
-        )
-        self.state = State.CONSOLIDATED
+    fractal_table_version: str | None = None
+    type: str | None = None
+    backend: str | None = None
 
-    @property
-    def root_path(self) -> str:
-        """Return the path of the root group.
 
-        This is in general the path of the NGFFImage.
-        """
-        return str(self._table_group.store.path)
+class GenericTable:
+    """Class to a non-specific table.
 
-    @property
-    def group_path(self) -> str:
-        """Return the path of the group.
+    This can be used to load any table that does not have
+    a specific definition.
+    """
 
-        This is the path of the group containing the table.
+    def __init__(
+        self,
+        dataframe: pd.DataFrame,
+    ) -> None:
+        """Initialize the GenericTable."""
+        self._meta = GenericTableMeta()
+        self._dataframe = dataframe
+        self._table_backend = None
+
+    @staticmethod
+    def type() -> str:
+        """Return the type of the table."""
+        return "generic"
+
+    @staticmethod
+    def version() -> str:
+        """The generic table does not have a version.
+
+        Since does not follow a specific schema.
         """
-        root = self.root_path
-        if root.endswith("/"):
-            root = root[:-1]
-
-        return f"{root}/{self._table_group.path}"
+        return "1"
 
     @property
-    def table(self) -> pd.DataFrame:
-        """Return the ROI table as a DataFrame."""
-        return self._table
-
-    @table.setter
-    def table(self, table: pd.DataFrame) -> None:
-        raise NotImplementedError(
-            "Setting the table directly is not supported. "
-            "Please use the 'set_table' method."
-        )
-
-    def set_table(self, table: pd.DataFrame) -> None:
-        table = validate_table(
-            table_df=table,
-            index_key=self.index_key,
-            index_type=self.index_type,
-            validators=self._validators,
-        )
-        self._table = table
-
-    def as_anndata(self) -> ad.AnnData:
-        """Return the ROI table as an AnnData object."""
-        return table_df_to_ad(
-            self.table, index_key=self.index_key, index_type=self.index_type
-        )
-
-    def from_anndata(self, table_ad: ad.AnnData) -> None:
-        """Return the ROI table as an AnnData object."""
-        table = table_ad_to_df(
-            table_ad=table_ad,
-            index_key=self.index_key,
-            index_type=self.index_type,
-            validators=self._validators,
-        )
-        # Don't use the setter to avoid re-validating the table
-        self._table = table
-
-    @property
-    def index(self) -> list[int | str]:
-        """Return a list of all the labels in the table."""
-        return self.table.index.tolist()
+    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 group(self) -> zarr.Group:
-        """Return the group of the table."""
-        return self._table_group
-
-    @property
-    def index_key(self) -> str:
-        """Return the index key of the table."""
-        return self._index_key
-
-    @property
-    def index_type(self) -> Literal["int", "str"]:
-        """Return the index type of the table."""
-        return self._index_type
+    def dataframe(self) -> pd.DataFrame:
+        """Return the table as a DataFrame."""
+        return self._dataframe
+
+    @dataframe.setter
+    def dataframe(self, dataframe: pd.DataFrame) -> None:
+        """Set the table as a DataFrame."""
+        self._dataframe = dataframe
+
+    @classmethod
+    def _from_handler(
+        cls, handler: ZarrGroupHandler, backend_name: str | None = None
+    ) -> "GenericTable":
+        """Create a new ROI table from a Zarr group handler."""
+        meta = GenericTableMeta(**handler.load_attrs())
+        if backend_name is None:
+            backend = ImplementedTableBackends().get_backend(
+                backend_name=meta.backend,
+                group_handler=handler,
+                index_key=None,
+            )
+        else:
+            backend = ImplementedTableBackends().get_backend(
+                backend_name=backend_name,
+                group_handler=handler,
+                index_key=None,
+            )
+            meta.backend = backend_name
+
+        if not backend.implements_dataframe:
+            raise ValueError("The backend does not implement the dataframe protocol.")
+
+        dataframe = backend.load_as_dataframe()
+
+        table = cls(dataframe)
+        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."""
+        backend = ImplementedTableBackends().get_backend(
+            backend_name=backend_name,
+            group_handler=handler,
+            index_key=None,
+        )
+        self._meta.backend = backend_name
+        self._table_backend = backend
 
-    @property
-    def validators(self) -> list[Validator] | None:
-        """Return the validators of the table."""
-        return self._validators
-
-    @validators.setter
-    def validators(self, validators: list[Validator] | None) -> None:
-        """Set the validators of the table."""
-        self._validators = validators
-
-    def add_validator(self, validator: Validator) -> None:
-        """Add a validator to the table."""
-        if self._validators is None:
-            self._validators = []
-        self._validators.append(validator)
-
-    def consolidate(self, meta: BaseModel) -> None:
+    def consolidate(self) -> None:
         """Write the current state of the table to the Zarr file."""
-        table = self.table
-        table = validate_table(
-            table_df=table,
-            index_key=self.index_key,
-            index_type=self.index_type,
-            validators=self._validators,
-        )
-        write_table_ad(
-            group=self._table_group,
-            table=self.table,
-            index_key=self.index_key,
-            index_type=self.index_type,
-            meta=meta,
-            validators=self._validators,
+        if self._table_backend is None:
+            raise ValueError(
+                "No backend set for the table. "
+                "Please add the table to a OME-Zarr Image before calling consolidate."
+            )
+
+        self._table_backend.write_from_dataframe(
+            self._dataframe, metadata=self._meta.model_dump(exclude_none=True)
         )

ngio/tables/v1/_masking_roi_table.py

@@ -0,0 +1,175 @@
+"""Implementation of the Masking ROI table class.
+
+This class follows the roi_table specification at:
+https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
+"""
+
+from collections.abc import Iterable
+from typing import Literal
+
+from pydantic import BaseModel
+
+from ngio.common import WorldCooROI
+from ngio.tables._validators import validate_columns
+from ngio.tables.backends import ImplementedTableBackends
+from ngio.tables.v1._roi_table import (
+    OPTIONAL_COLUMNS,
+    REQUIRED_COLUMNS,
+    _dataframe_to_rois,
+    _rois_to_dataframe,
+)
+from ngio.utils import NgioValueError, ZarrGroupHandler
+
+
+class RegionMeta(BaseModel):
+    """Metadata for the region."""
+
+    path: str
+
+
+class MaskingROITableV1Meta(BaseModel):
+    """Metadata for the ROI table."""
+
+    fractal_table_version: Literal["1"] = "1"
+    type: Literal["masking_roi_table"] = "masking_roi_table"
+    backend: str | None = None
+    region: RegionMeta | None = None
+    instance_key: str = "label"
+
+
+class MaskingROITableV1:
+    """Class to handle fractal ROI tables.
+
+    To know more about the ROI table format, please refer to the
+    specification at:
+    https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
+    """
+
+    def __init__(
+        self,
+        rois: Iterable[WorldCooROI] | None = None,
+        reference_label: str | None = None,
+    ) -> None:
+        """Create a new ROI table."""
+        if reference_label is None:
+            self._meta = MaskingROITableV1Meta()
+        else:
+            path = f"../labels/{reference_label}"
+            self._meta = MaskingROITableV1Meta(region=RegionMeta(path=path))
+        self._table_backend = None
+
+        self._rois = {}
+        if rois is not None:
+            self.add(rois)
+
+    @staticmethod
+    def type() -> Literal["masking_roi_table"]:
+        """Return the type of the table."""
+        return "masking_roi_table"
+
+    @staticmethod
+    def version() -> Literal["1"]:
+        """Return the version of the fractal table."""
+        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()
+
+    @classmethod
+    def _from_handler(
+        cls, handler: ZarrGroupHandler, backend_name: str | None = None
+    ) -> "MaskingROITableV1":
+        """Create a new ROI table from a Zarr store."""
+        meta = MaskingROITableV1Meta(**handler.load_attrs())
+
+        if backend_name is None:
+            backend = ImplementedTableBackends().get_backend(
+                backend_name=meta.backend,
+                group_handler=handler,
+                index_key="label",
+                index_type="int",
+            )
+        else:
+            backend = ImplementedTableBackends().get_backend(
+                backend_name=backend_name,
+                group_handler=handler,
+                index_key="label",
+                index_type="int",
+            )
+            meta.backend = backend_name
+
+        if not backend.implements_dataframe:
+            raise NgioValueError(
+                "The backend does not implement the dataframe protocol."
+            )
+
+        table = cls()
+        table._meta = meta
+        table._table_backend = backend
+
+        dataframe = backend.load_as_dataframe()
+        dataframe = validate_columns(
+            dataframe,
+            required_columns=REQUIRED_COLUMNS,
+            optional_columns=OPTIONAL_COLUMNS,
+        )
+        table._rois = _dataframe_to_rois(dataframe)
+        return table
+
+    def _set_backend(
+        self,
+        handler: ZarrGroupHandler,
+        backend_name: str | None = None,
+    ) -> None:
+        """Set the backend of the table."""
+        backend = ImplementedTableBackends().get_backend(
+            backend_name=backend_name,
+            group_handler=handler,
+            index_key="label",
+            index_type="int",
+        )
+        self._meta.backend = backend_name
+        self._table_backend = backend
+
+    def rois(self) -> list[WorldCooROI]:
+        """List all ROIs in the table."""
+        return list(self._rois.values())
+
+    def get(self, label: int) -> WorldCooROI:
+        """Get an ROI from the table."""
+        _label = str(label)
+        if _label not in self._rois:
+            raise KeyError(f"ROI {_label} not found in the table.")
+        return self._rois[_label]
+
+    def add(self, roi: WorldCooROI | Iterable[WorldCooROI]) -> None:
+        """Append ROIs to the current table."""
+        if isinstance(roi, WorldCooROI):
+            roi = [roi]
+
+        for _roi in roi:
+            if _roi.name in self._rois:
+                raise NgioValueError(f"ROI {_roi.name} already exists in the table.")
+            self._rois[_roi.name] = _roi
+
+    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."
+            )
+
+        dataframe = _rois_to_dataframe(self._rois, index_key="label")
+        dataframe = validate_columns(
+            dataframe,
+            required_columns=REQUIRED_COLUMNS,
+            optional_columns=OPTIONAL_COLUMNS,
+        )
+        self._table_backend.write_from_dataframe(
+            dataframe, metadata=self._meta.model_dump(exclude_none=True)
+        )

ngio/tables/v1/_roi_table.py

@@ -0,0 +1,226 @@
+"""Implementation of the ROI Table class.
+
+This class follows the roi_table specification at:
+https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
+"""
+
+from collections.abc import Iterable
+from typing import Literal
+
+import pandas as pd
+from pydantic import BaseModel
+
+from ngio.common import WorldCooROI
+from ngio.tables._validators import validate_columns
+from ngio.tables.backends import ImplementedTableBackends
+from ngio.utils import NgioValueError, ZarrGroupHandler
+
+REQUIRED_COLUMNS = [
+    "x_micrometer",
+    "y_micrometer",
+    "z_micrometer",
+    "len_x_micrometer",
+    "len_y_micrometer",
+    "len_z_micrometer",
+]
+
+
+ORIGIN_COLUMNS = [
+    "x_micrometer_original",
+    "y_micrometer_original",
+]
+
+TRANSLATION_COLUMNS = ["translation_x", "translation_y", "translation_z"]
+
+OPTIONAL_COLUMNS = ORIGIN_COLUMNS + TRANSLATION_COLUMNS
+
+
+def _dataframe_to_rois(dataframe: pd.DataFrame) -> dict[str, WorldCooROI]:
+    """Convert a DataFrame to a WorldCooROI object."""
+    rois = {}
+    for key, row in dataframe.iterrows():
+        # check if optional columns are present
+        origin = {col: row.get(col, None) for col in ORIGIN_COLUMNS}
+        origin = dict(filter(lambda x: x[1] is not None, origin.items()))
+        translation = {col: row.get(col, None) for col in TRANSLATION_COLUMNS}
+        translation = dict(filter(lambda x: x[1] is not None, translation.items()))
+
+        roi = WorldCooROI(
+            name=str(key),
+            x=row["x_micrometer"],
+            y=row["y_micrometer"],
+            z=row["z_micrometer"],
+            x_length=row["len_x_micrometer"],
+            y_length=row["len_y_micrometer"],
+            z_length=row["len_z_micrometer"],
+            unit="micrometer",  # type: ignore
+            **origin,
+            **translation,
+        )
+        rois[roi.name] = roi
+    return rois
+
+
+def _rois_to_dataframe(rois: dict[str, WorldCooROI], index_key: str) -> pd.DataFrame:
+    """Convert a list of WorldCooROI objects to a DataFrame."""
+    data = []
+    for roi in rois.values():
+        row = {
+            index_key: roi.name,
+            "x_micrometer": roi.x,
+            "y_micrometer": roi.y,
+            "z_micrometer": roi.z,
+            "len_x_micrometer": roi.x_length,
+            "len_y_micrometer": roi.y_length,
+            "len_z_micrometer": roi.z_length,
+        }
+
+        extra = roi.model_extra or {}
+        for col in ORIGIN_COLUMNS:
+            if col in extra:
+                row[col] = extra[col]
+
+        for col in TRANSLATION_COLUMNS:
+            if col in extra:
+                row[col] = extra[col]
+        data.append(row)
+    dataframe = pd.DataFrame(data)
+    dataframe = dataframe.set_index(index_key)
+    return dataframe
+
+
+class ROITableV1Meta(BaseModel):
+    """Metadata for the ROI table."""
+
+    fractal_table_version: Literal["1"] = "1"
+    type: Literal["roi_table"] = "roi_table"
+    backend: str | None = None
+
+
+class RoiTableV1:
+    """Class to handle fractal ROI tables.
+
+    To know more about the ROI table format, please refer to the
+    specification at:
+    https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
+    """
+
+    def __init__(self, rois: Iterable[WorldCooROI] | None = None) -> None:
+        """Create a new ROI table."""
+        self._meta = ROITableV1Meta()
+        self._table_backend = None
+
+        self._rois = {}
+        if rois is not None:
+            self.add(rois)
+
+    @staticmethod
+    def type() -> Literal["roi_table"]:
+        """Return the type of the table."""
+        return "roi_table"
+
+    @staticmethod
+    def version() -> Literal["1"]:
+        """Return the version of the fractal table."""
+        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()
+
+    @classmethod
+    def _from_handler(
+        cls, handler: ZarrGroupHandler, backend_name: str | None = None
+    ) -> "RoiTableV1":
+        """Create a new ROI table from a Zarr store."""
+        meta = ROITableV1Meta(**handler.load_attrs())
+
+        if backend_name is None:
+            backend = ImplementedTableBackends().get_backend(
+                backend_name=meta.backend,
+                group_handler=handler,
+                index_key="FieldIndex",
+                index_type="str",
+            )
+        else:
+            backend = ImplementedTableBackends().get_backend(
+                backend_name=backend_name,
+                group_handler=handler,
+                index_key="FieldIndex",
+                index_type="str",
+            )
+            meta.backend = backend_name
+
+        if not backend.implements_dataframe:
+            raise NgioValueError(
+                "The backend does not implement the dataframe protocol."
+            )
+
+        table = cls()
+        table._meta = meta
+        table._table_backend = backend
+
+        dataframe = backend.load_as_dataframe()
+        dataframe = validate_columns(
+            dataframe,
+            required_columns=REQUIRED_COLUMNS,
+            optional_columns=OPTIONAL_COLUMNS,
+        )
+        table._rois = _dataframe_to_rois(dataframe)
+        return table
+
+    def _set_backend(
+        self,
+        handler: ZarrGroupHandler,
+        backend_name: str | None = None,
+    ) -> None:
+        """Set the backend of the table."""
+        backend = ImplementedTableBackends().get_backend(
+            backend_name=backend_name,
+            group_handler=handler,
+            index_key="FieldIndex",
+            index_type="str",
+        )
+        self._meta.backend = backend_name
+        self._table_backend = backend
+
+    def rois(self) -> list[WorldCooROI]:
+        """List all ROIs in the table."""
+        return list(self._rois.values())
+
+    def get(self, roi_name: str) -> WorldCooROI:
+        """Get an ROI from the table."""
+        if roi_name not in self._rois:
+            raise NgioValueError(f"ROI {roi_name} not found in the table.")
+        return self._rois[roi_name]
+
+    def add(self, roi: WorldCooROI | Iterable[WorldCooROI]) -> None:
+        """Append ROIs to the current table."""
+        if isinstance(roi, WorldCooROI):
+            roi = [roi]
+
+        for _roi in roi:
+            if _roi.name in self._rois:
+                raise NgioValueError(f"ROI {_roi.name} already exists in the table.")
+            self._rois[_roi.name] = _roi
+
+    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."
+            )
+
+        dataframe = _rois_to_dataframe(self._rois, index_key="FieldIndex")
+        dataframe = validate_columns(
+            dataframe,
+            required_columns=REQUIRED_COLUMNS,
+            optional_columns=OPTIONAL_COLUMNS,
+        )
+        self._table_backend.write_from_dataframe(
+            dataframe, metadata=self._meta.model_dump(exclude_none=True)
+        )