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

ngio/tables/tables_container.py

@@ -0,0 +1,300 @@
+"""Module for handling the /tables group in an OME-NGFF file."""
+
+from typing import Literal, Protocol
+
+from ngio.tables.v1 import FeatureTableV1, MaskingROITableV1, RoiTableV1
+from ngio.tables.v1._generic_table import GenericTable
+from ngio.utils import (
+    AccessModeLiteral,
+    NgioValidationError,
+    NgioValueError,
+    StoreOrGroup,
+    ZarrGroupHandler,
+)
+
+RoiTable = RoiTableV1
+MaskingROITable = MaskingROITableV1
+FeatureTable = FeatureTableV1
+
+
+class Table(Protocol):
+    """Placeholder class for a table."""
+
+    @staticmethod
+    def type() -> str | None:
+        """Return the type of the table."""
+        ...
+
+    @staticmethod
+    def version() -> str | None:
+        """Return the version of the table."""
+        ...
+
+    @property
+    def backend_name(self) -> str | None:
+        """The name of the backend."""
+        ...
+
+    @classmethod
+    def _from_handler(
+        cls, handler: ZarrGroupHandler, backend_name: str | 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."""
+        ...
+
+    def consolidate(self) -> None:
+        """Consolidate the table on disk."""
+        ...
+
+
+TypedTable = Literal["roi_table", "masking_roi_table", "feature_table"]
+
+
+def _unique_table_name(type_name, version) -> str:
+    """Return the unique name for a table."""
+    return f"{type_name}_v{version}"
+
+
+class ImplementedTables:
+    """A singleton class to manage the available table handler plugins."""
+
+    _instance = None
+    _implemented_tables: dict[str, type[Table]]
+
+    def __new__(cls):
+        """Create a new instance of the class if it does not exist."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._implemented_tables = {}
+        return cls._instance
+
+    def available_implementations(self) -> list[str]:
+        """Get the available table handler versions."""
+        return list(self._implemented_tables.keys())
+
+    def get_table(
+        self,
+        type: str,
+        version: str,
+        handler: ZarrGroupHandler,
+        backend_name: str | None = None,
+    ) -> 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:
+                _errors[name] = e
+        print(_errors)
+        # 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 len(_errors) == 0:
+            raise NgioValidationError(
+                f"Could not find a table implementation for {type} v{version}. "
+                f"Available tables: {self.available_implementations()}"
+            )
+
+        raise NgioValidationError(
+            f"Could not load table from any known version. Errors: {_errors}"
+        )
+
+    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.")
+
+        table_unique_name = _unique_table_name(table_type, version)
+        if table_unique_name in self._implemented_tables and not overwrite:
+            raise NgioValueError(
+                f"Table handler for {table_unique_name} already exists. "
+                "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")
+
+
+class TablesContainer:
+    """A class to handle the /labels group in an OME-NGFF file."""
+
+    def __init__(self, group_handler: ZarrGroupHandler) -> None:
+        """Initialize the LabelGroupHandler."""
+        self._group_handler = group_handler
+
+        # Validate the group
+        # Either contains a tables attribute or is empty
+        attrs = self._group_handler.load_attrs()
+        if len(attrs) == 0:
+            # It's an empty group
+            pass
+        elif "tables" in attrs and isinstance(attrs["tables"], list):
+            # It's a valid group
+            pass
+        else:
+            raise NgioValidationError(
+                f"Invalid /tables group. "
+                f"Expected a single tables attribute with a list of table names. "
+                f"Found: {attrs}"
+            )
+
+    def _get_tables_list(self) -> list[str]:
+        """Create the /tables group if it doesn't exist."""
+        attrs = self._group_handler.load_attrs()
+        return attrs.get("tables", [])
+
+    def _get_table_group_handler(self, name: str) -> ZarrGroupHandler:
+        """Get the group handler for a table."""
+        handler = self._group_handler.derive_handler(path=name)
+        return handler
+
+    def list(self, filter_types: str | None = None) -> list[str]:
+        """List all labels in the group."""
+        tables = self._get_tables_list()
+        if filter_types is None:
+            return tables
+
+        filtered_tables = []
+        for table_name in tables:
+            tb_handler = self._get_table_group_handler(table_name)
+            table_type = _get_table_type(tb_handler)
+            if table_type == filter_types:
+                filtered_tables.append(table_name)
+        return filtered_tables
+
+    def get(self, name: str, backend_name: str | None = None) -> Table:
+        """Get a label from the group."""
+        if name not in self.list():
+            raise KeyError(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)
+        return ImplementedTables().get_table(
+            type=table_type,
+            version=table_version,
+            handler=table_handler,
+            backend_name=backend_name,
+        )
+
+    def add(
+        self,
+        name: str,
+        table: Table,
+        backend: str | None = None,
+        overwrite: bool = False,
+    ) -> None:
+        """Add a table to the group."""
+        existing_tables = self._get_tables_list()
+        if name in existing_tables and not overwrite:
+            raise NgioValueError(
+                f"Table '{name}' already exists in the group. "
+                "Use overwrite=True to replace it."
+            )
+
+        table_handler = self._group_handler.derive_handler(path=name)
+
+        if backend is None:
+            backend = table.backend_name
+
+        table._set_backend(
+            handler=table_handler,
+            backend_name=backend,
+        )
+        table.consolidate()
+        if name not in existing_tables:
+            existing_tables.append(name)
+            self._group_handler.write_attrs({"tables": existing_tables})
+
+
+ImplementedTables().add_implementation(RoiTableV1)
+ImplementedTables().add_implementation(MaskingROITableV1)
+ImplementedTables().add_implementation(FeatureTableV1)
+
+###################################################################################
+#
+# Utility functions to open and write tables
+#
+###################################################################################
+
+
+def open_tables_container(
+    store: StoreOrGroup,
+    cache: bool = False,
+    mode: AccessModeLiteral = "a",
+    parallel_safe: bool = False,
+) -> TablesContainer:
+    """Open a table handler from a Zarr store."""
+    handler = ZarrGroupHandler(
+        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
+    )
+    return TablesContainer(handler)
+
+
+def open_table(
+    store: StoreOrGroup,
+    cache: bool = False,
+    mode: AccessModeLiteral = "a",
+    parallel_safe: bool = False,
+) -> Table:
+    """Open a table from a Zarr store."""
+    handler = ZarrGroupHandler(
+        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
+    )
+    return ImplementedTables().get_table(
+        _get_table_type(handler), _get_table_version(handler), handler
+    )
+
+
+def write_table(
+    store: StoreOrGroup,
+    table: Table,
+    backend: str | None = None,
+    cache: bool = False,
+    mode: AccessModeLiteral = "a",
+    parallel_safe: bool = False,
+) -> None:
+    """Write a table to a Zarr store."""
+    handler = ZarrGroupHandler(
+        store=store, cache=cache, mode=mode, parallel_safe=parallel_safe
+    )
+    table._set_backend(
+        handler=handler,
+        backend_name=backend,
+    )
+    table.consolidate()

ngio/tables/v1/__init__.py

@@ -1,7 +1,8 @@
-"""This module contains the objects to handle the fractal tables V1."""
+"""Tables implementations for fractal_tables v1."""
 
-from ngio.tables.v1.feature_tables import FeatureTableV1
-from ngio.tables.v1.masking_roi_tables import MaskingROITableV1
-from ngio.tables.v1.roi_tables import ROITableV1
+from ngio.tables.v1._feature_table import FeatureTableV1
+from ngio.tables.v1._generic_table import GenericTable
+from ngio.tables.v1._masking_roi_table import MaskingROITableV1
+from ngio.tables.v1._roi_table import RoiTableV1
 
-__all__ = ["ROITableV1", "FeatureTableV1", "MaskingROITableV1"]
+__all__ = ["FeatureTableV1", "GenericTable", "MaskingROITableV1", "RoiTableV1"]

ngio/tables/v1/_feature_table.py

@@ -0,0 +1,161 @@
+"""Implementation of the FeatureTableV1 class.
+
+This class follows the roi_table specification at:
+https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
+"""
+
+from typing import Literal
+
+import pandas as pd
+from pydantic import BaseModel
+
+from ngio.tables._validators import validate_index_key
+from ngio.tables.backends import ImplementedTableBackends
+from ngio.utils import ZarrGroupHandler
+
+
+class RegionMeta(BaseModel):
+    """Metadata for the region."""
+
+    path: str
+
+
+class FeatureTableMeta(BaseModel):
+    """Metadata for the ROI table."""
+
+    fractal_table_version: Literal["1"] = "1"
+    type: Literal["feature_table"] = "feature_table"
+    backend: str | None = None
+    region: RegionMeta | None = None
+    instance_key: str = "label"
+
+
+class FeatureTableV1:
+    """Class to represent a feature table.
+
+    This can be used to load any table that does not have
+    a specific definition.
+    """
+
+    def __init__(
+        self,
+        dataframe: pd.DataFrame | None = None,
+        reference_label: str | None = None,
+    ) -> None:
+        """Initialize the GenericTable."""
+        if reference_label is None:
+            self._meta = FeatureTableMeta()
+        else:
+            path = f"../labels/{reference_label}"
+            self._meta = FeatureTableMeta(region=RegionMeta(path=path))
+
+        self._reference_label = reference_label
+        self._instance_key = "label"
+        if dataframe is None:
+            self._dataframe = None
+        else:
+            self._dataframe = validate_index_key(
+                dataframe, self._instance_key, overwrite=True
+            )
+        self._table_backend = None
+
+    @staticmethod
+    def type() -> str:
+        """Return the type of the table."""
+        return "feature_table"
+
+    @staticmethod
+    def version() -> str:
+        """The generic table does not have a version.
+
+        Since does not follow a specific schema.
+        """
+        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 dataframe(self) -> pd.DataFrame:
+        """Return the table as a DataFrame."""
+        if self._dataframe is None and self._table_backend is None:
+            raise ValueError(
+                "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_dataframe()
+
+        if self._dataframe is None:
+            raise ValueError(
+                "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 = dataframe
+
+    @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_dataframe:
+            raise ValueError("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 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)
+        )