ngio 0.2.0a2__py3-none-any.whl → 0.5.0b4__py3-none-any.whl

ngio/ome_zarr_meta/_generic_handlers.py

@@ -1,320 +0,0 @@
-"""Base class for handling OME-NGFF metadata in Zarr groups."""
-
-from typing import Generic, Protocol, TypeVar
-
-from pydantic import ValidationError
-
-from ngio.ome_zarr_meta.ngio_specs import AxesSetup, NgioImageMeta, NgioLabelMeta
-from ngio.utils import (
-    NgioValueError,
-    ZarrGroupHandler,
-)
-
-ConverterError = ValidationError | Exception | None
-
-
-class ImageMetaHandler(Protocol):
-    """Protocol for OME-Zarr image handlers."""
-
-    def __init__(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        """Initialize the handler."""
-        ...
-
-    def safe_load_meta(self) -> NgioImageMeta | ConverterError:
-        """Load the metadata from the store."""
-        ...
-
-    @property
-    def meta(self) -> NgioImageMeta:
-        """Return the metadata."""
-        ...
-
-    def write_meta(self, meta: NgioImageMeta) -> None:
-        """Write the metadata to the store."""
-        ...
-
-
-class LabelMetaHandler(Protocol):
-    """Protocol for OME-Zarr label handlers."""
-
-    def __init__(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        """Initialize the handler."""
-        ...
-
-    def safe_load_meta(self) -> NgioLabelMeta | ConverterError:
-        """Load the metadata from the store."""
-        ...
-
-    @property
-    def meta(self) -> NgioLabelMeta:
-        """Return the metadata."""
-        ...
-
-    def write_meta(self, meta: NgioLabelMeta) -> None:
-        """Write the metadata to the store."""
-        ...
-
-
-###########################################################################
-#
-# The code below implements a generic class for handling OME-Zarr metadata
-# in Zarr groups.
-#
-###########################################################################
-
-
-class ImageMetaImporter(Protocol):
-    @staticmethod
-    def __call__(
-        metadata: dict,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ) -> tuple[bool, NgioImageMeta | ConverterError]:
-        """Convert the metadata to a NgioImageMeta object.
-
-        Args:
-            metadata (dict): The metadata (typically from a Zarr group .attrs).
-            axes_setup (AxesSetup, optional): The axes setup.
-                This is used to map axes with non-canonical names.
-            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
-                axes.
-            strict_canonical_order (bool, optional): Whether to enforce a strict
-                canonical order.
-
-        Returns:
-            tuple[bool, NgioImageMeta | ConverterError]: A tuple with a boolean
-                indicating whether the conversion was successful and the
-                NgioImageMeta object or an error.
-
-        """
-        ...
-
-
-class ImageMetaExporter(Protocol):
-    def __call__(self, metadata: NgioImageMeta) -> dict: ...
-
-
-class LabelMetaImporter(Protocol):
-    @staticmethod
-    def __call__(
-        metadata: dict,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ) -> tuple[bool, NgioLabelMeta | ConverterError]:
-        """Convert the metadata to a NgioLabelMeta object.
-
-        Args:
-            metadata (dict): The metadata (typically from a Zarr group .attrs).
-            axes_setup (AxesSetup, optional): The axes setup.
-                This is used to map axes with non-canonical names.
-            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
-                axes.
-            strict_canonical_order (bool, optional): Whether to enforce a strict
-                canonical order.
-
-        Returns:
-            tuple[bool, NgioLabelMeta | ConverterError]: A tuple with a boolean
-                indicating whether the conversion was successful and the
-                NgioLabelMeta object or an error.
-
-        """
-        ...
-
-
-class LabelMetaExporter(Protocol):
-    def __call__(self, metadata: NgioLabelMeta) -> dict: ...
-
-
-_meta = TypeVar("_meta", NgioImageMeta, NgioLabelMeta)
-_meta_importer = TypeVar("_meta_importer", ImageMetaImporter, LabelMetaImporter)
-_meta_exporter = TypeVar("_meta_exporter", ImageMetaExporter, LabelMetaExporter)
-
-
-class GenericMetaHandler(Generic[_meta, _meta_importer, _meta_exporter]):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
-
-    def __init__(
-        self,
-        meta_importer: _meta_importer,
-        meta_exporter: _meta_exporter,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        """Initialize the handler.
-
-        Args:
-            meta_importer (MetaImporter): The metadata importer.
-            meta_exporter (MetaExporter): The metadata exporter.
-            group_handler (ZarrGroupHandler): The Zarr group handler.
-            axes_setup (AxesSetup, optional): The axes setup.
-                This is used to map axes with non-canonical names.
-            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
-                axes.
-            strict_canonical_order (bool, optional): Whether to enforce a strict
-                canonical order.
-        """
-        self._group_handler = group_handler
-        self._meta_importer = meta_importer
-        self._meta_exporter = meta_exporter
-        self._axes_setup = axes_setup
-        self._allow_non_canonical_axes = allow_non_canonical_axes
-        self._strict_canonical_order = strict_canonical_order
-
-    def _load_meta(self, return_error: bool = False):
-        """Load the metadata from the store."""
-        attrs = self._group_handler.load_attrs()
-        is_valid, meta_or_error = self._meta_importer(
-            metadata=attrs,
-            axes_setup=self._axes_setup,
-            allow_non_canonical_axes=self._allow_non_canonical_axes,
-            strict_canonical_order=self._strict_canonical_order,
-        )
-        if is_valid:
-            return meta_or_error
-
-        if return_error:
-            return meta_or_error
-
-        raise NgioValueError(f"Could not load metadata: {meta_or_error}")
-
-    def safe_load_meta(self) -> _meta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
-
-    def _write_meta(self, meta) -> None:
-        """Write the metadata to the store."""
-        v04_meta = self._meta_exporter(metadata=meta)
-        self._group_handler.write_attrs(v04_meta)
-
-    def write_meta(self, meta: _meta) -> None:
-        """Write the metadata to the store."""
-        raise NotImplementedError
-
-    @property
-    def meta(self) -> _meta:
-        """Return the metadata."""
-        raise NotImplementedError
-
-
-class BaseImageMetaHandler(
-    GenericMetaHandler[NgioImageMeta, ImageMetaImporter, ImageMetaExporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
-
-    def __init__(
-        self,
-        meta_importer: ImageMetaImporter,
-        meta_exporter: ImageMetaExporter,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        """Initialize the handler.
-
-        Args:
-            meta_importer (ImageMetaImporter): The metadata importer.
-            meta_exporter (ImageMetaExporter): The metadata exporter.
-            group_handler (ZarrGroupHandler): The Zarr group handler.
-            axes_setup (AxesSetup, optional): The axes setup.
-                This is used to map axes with non-canonical names.
-            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
-                axes.
-            strict_canonical_order (bool, optional): Whether to enforce a strict
-                canonical order.
-        """
-        super().__init__(
-            meta_importer=meta_importer,
-            meta_exporter=meta_exporter,
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )
-
-    def safe_load_meta(
-        self, return_error: bool = False
-    ) -> NgioImageMeta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error)
-
-    @property
-    def meta(self) -> NgioImageMeta:
-        """Load the metadata from the store."""
-        meta = self._load_meta()
-        if isinstance(meta, NgioImageMeta):
-            return meta
-        raise NgioValueError(f"Could not load metadata: {meta}")
-
-    def write_meta(self, meta: NgioImageMeta) -> None:
-        self._write_meta(meta)
-
-
-class BaseLabelMetaHandler(
-    GenericMetaHandler[NgioLabelMeta, LabelMetaImporter, LabelMetaExporter]
-):
-    """Generic class for handling OME-Zarr metadata in Zarr groups."""
-
-    def __init__(
-        self,
-        meta_importer: LabelMetaImporter,
-        meta_exporter: LabelMetaExporter,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        """Initialize the handler.
-
-        Args:
-            meta_importer (LabelMetaImporter): The metadata importer.
-            meta_exporter (LabelMetaExporter): The metadata exporter.
-            group_handler (ZarrGroupHandler): The Zarr group handler.
-            axes_setup (AxesSetup, optional): The axes setup.
-                This is used to map axes with non-canonical names.
-            allow_non_canonical_axes (bool, optional): Whether to allow non-canonical
-                axes.
-            strict_canonical_order (bool, optional): Whether to enforce a strict
-                canonical order.
-        """
-        super().__init__(
-            meta_importer=meta_importer,
-            meta_exporter=meta_exporter,
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )
-
-    def safe_load_meta(
-        self, return_error: bool = False
-    ) -> NgioLabelMeta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error)
-
-    @property
-    def meta(self) -> NgioLabelMeta:
-        """Load the metadata from the store."""
-        meta = self._load_meta()
-        if isinstance(meta, NgioLabelMeta):
-            return meta
-        raise NgioValueError(f"Could not load metadata: {meta}")
-
-    def write_meta(self, meta: NgioLabelMeta) -> None:
-        self._write_meta(meta)

ngio/ome_zarr_meta/v04/_meta_handlers.py

@@ -1,54 +0,0 @@
-"""Concrete implementation of the OME-Zarr metadata handlers for version 0.4."""
-
-from ngio.ome_zarr_meta._generic_handlers import (
-    BaseImageMetaHandler,
-    BaseLabelMetaHandler,
-)
-from ngio.ome_zarr_meta.ngio_specs import AxesSetup
-from ngio.ome_zarr_meta.v04._v04_spec_utils import (
-    ngio_to_v04_image_meta,
-    ngio_to_v04_label_meta,
-    v04_to_ngio_image_meta,
-    v04_to_ngio_label_meta,
-)
-from ngio.utils import ZarrGroupHandler
-
-
-class V04ImageMetaHandler(BaseImageMetaHandler):
-    """Base class for handling OME-Zarr 0.4 metadata."""
-
-    def __init__(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        super().__init__(
-            meta_importer=v04_to_ngio_image_meta,
-            meta_exporter=ngio_to_v04_image_meta,
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )
-
-
-class V04LabelMetaHandler(BaseLabelMetaHandler):
-    """Base class for handling OME-Zarr 0.4 metadata."""
-
-    def __init__(
-        self,
-        group_handler: ZarrGroupHandler,
-        axes_setup: AxesSetup | None = None,
-        allow_non_canonical_axes: bool = False,
-        strict_canonical_order: bool = True,
-    ):
-        super().__init__(
-            meta_importer=v04_to_ngio_label_meta,
-            meta_exporter=ngio_to_v04_label_meta,
-            group_handler=group_handler,
-            axes_setup=axes_setup,
-            allow_non_canonical_axes=allow_non_canonical_axes,
-            strict_canonical_order=strict_canonical_order,
-        )

ngio/tables/_validators.py

@@ -1,192 +0,0 @@
-from collections.abc import Iterable
-from typing import Protocol
-
-import pandas as pd
-import pandas.api.types as ptypes
-
-from ngio.utils import (
-    NgioTableValidationError,
-)
-
-
-class TableValidator(Protocol):
-    def __call__(self, table: pd.DataFrame) -> pd.DataFrame:
-        """Validate the table DataFrame.
-
-        A Validator is just a simple callable that takes a
-            DataFrame and returns a DataFrame.
-
-        If the DataFrame is valid, the same DataFrame is returned.
-        If the DataFrame is invalid, the Validator can either modify the DataFrame
-            to make it valid or raise a NgioTableValidationError.
-
-        Args:
-            table (pd.DataFrame): The DataFrame to validate.
-
-        Returns:
-            pd.DataFrame: The validated DataFrame.
-
-        """
-        ...
-
-
-def validate_table(
-    table_df: pd.DataFrame,
-    validators: Iterable[TableValidator] | None = None,
-) -> pd.DataFrame:
-    """Validate the table DataFrame.
-
-    Args:
-        table_df (pd.DataFrame): The DataFrame to validate.
-        validators (Collection[Validator] | None): A collection of functions
-            used to validate the table. Default is None.
-
-    Returns:
-        pd.DataFrame: The validated DataFrame.
-    """
-    validators = validators or []
-
-    # Apply all provided validators
-    for validator in validators:
-        table_df = validator(table_df)
-
-    return table_df
-
-
-####################################################################################################
-#
-# Common table validators
-#
-####################################################################################################
-def validate_index_key(
-    dataframe: pd.DataFrame, index_key: str | None, overwrite: bool = False
-) -> pd.DataFrame:
-    """Correctly set the index of the DataFrame.
-
-    This function checks if the index_key is present in the DataFrame.
-    If not it tries to set sensible defaults.
-
-    In order:
-        - If index_key is None, nothing can be done.
-        - If index_key is already the index of the DataFrame, nothing is done.
-        - If index_key is in the columns, we set the index to that column.
-        - If current index is None, we set the index to the index_key.
-        - If current index is not None and overwrite is True,
-            we set the index to the index_key.
-
-    """
-    if index_key is None:
-        # Nothing to do
-        return dataframe
-
-    if dataframe.index.name == index_key:
-        # Index is already set to index_key correctly
-        return dataframe
-
-    if index_key in dataframe.columns:
-        dataframe = dataframe.set_index(index_key)
-        return dataframe
-
-    if dataframe.index.name is None:
-        dataframe.index.name = index_key
-        return dataframe
-
-    elif overwrite:
-        dataframe.index.name = index_key
-        return dataframe
-    else:
-        raise NgioTableValidationError(
-            f"Index key {index_key} not found in DataFrame. "
-            f"Current index is {dataframe.index.name}. If you want to overwrite the "
-            "index set overwrite=True."
-        )
-
-
-def validate_index_dtype(dataframe: pd.DataFrame, index_type: str) -> pd.DataFrame:
-    """Check if the index of the DataFrame has the correct dtype."""
-    match index_type:
-        case "str":
-            if ptypes.is_integer_dtype(dataframe.index):
-                # Convert the int index to string is generally safe
-                dataframe = dataframe.set_index(dataframe.index.astype(str))
-
-            if not ptypes.is_string_dtype(dataframe.index):
-                raise NgioTableValidationError(
-                    f"Table index must be of string type, got {dataframe.index.dtype}"
-                )
-
-        case "int":
-            if ptypes.is_string_dtype(dataframe.index):
-                # Try to convert the string index to int
-                try:
-                    dataframe = dataframe.set_index(dataframe.index.astype(int))
-                except ValueError as e:
-                    if "invalid literal for int() with base 10" in str(e):
-                        raise NgioTableValidationError(
-                            "Table index must be of integer type, got str."
-                            f" We tried implicit conversion and failed: {e}"
-                        ) from None
-                    else:
-                        raise e from e
-
-            if not ptypes.is_integer_dtype(dataframe.index):
-                raise NgioTableValidationError(
-                    f"Table index must be of integer type, got {dataframe.index.dtype}"
-                )
-        case _:
-            raise ValueError(f"index_type {index_type} not recognized")
-
-    return dataframe
-
-
-def validate_columns(
-    table_df: pd.DataFrame,
-    required_columns: list[str],
-    optional_columns: list[str] | None = None,
-) -> pd.DataFrame:
-    """Validate the columns headers of the table.
-
-    If a required column is missing, a TableValidationError is raised.
-    If a list of optional columns is provided, only required and optional columns are
-        allowed in the table.
-
-    Args:
-        table_df (pd.DataFrame): The DataFrame to validate.
-        required_columns (list[str]): A list of required columns.
-        optional_columns (list[str] | None): A list of optional columns.
-            Default is None.
-
-    Returns:
-        pd.DataFrame: The validated DataFrame.
-    """
-    table_header = table_df.columns
-    for column in required_columns:
-        if column not in table_header:
-            raise NgioTableValidationError(
-                f"Could not find required column: {column} in the table"
-            )
-
-    if optional_columns is None:
-        return table_df
-
-    possible_columns = [*required_columns, *optional_columns]
-    for column in table_header:
-        if column not in possible_columns:
-            raise NgioTableValidationError(
-                f"Could not find column: {column} in the list of possible columns. ",
-                f"Possible columns are: {possible_columns}",
-            )
-
-    return table_df
-
-
-def validate_unique_index(table_df: pd.DataFrame) -> pd.DataFrame:
-    """Validate that the index of the table is unique."""
-    if table_df.index.is_unique:
-        return table_df
-
-    # Find the duplicates
-    duplicates = table_df.index[table_df.index.duplicated()].tolist()
-    raise NgioTableValidationError(
-        f"Index of the table contains duplicates values. Duplicate: {duplicates}"
-    )

ngio/tables/backends/_anndata_v1.py

@@ -1,75 +0,0 @@
-from collections.abc import Collection
-from pathlib import Path
-
-from anndata import AnnData
-from pandas import DataFrame
-
-from ngio.tables.backends._abstract_backend import AbstractTableBackend
-from ngio.tables.backends._anndata_utils import (
-    anndata_to_dataframe,
-    custom_read_zarr,
-    dataframe_to_anndata,
-)
-
-
-class AnnDataBackend(AbstractTableBackend):
-    """A class to load and write tables from/to an AnnData object."""
-
-    @staticmethod
-    def backend_name() -> str:
-        """The name of the backend."""
-        return "anndata_v1"
-
-    @staticmethod
-    def implements_anndata() -> bool:
-        """Whether the handler implements the anndata protocol."""
-        return True
-
-    @staticmethod
-    def implements_dataframe() -> bool:
-        """Whether the handler implements the dataframe protocol."""
-        return True
-
-    def load_columns(self) -> list[str]:
-        """List all labels in the group."""
-        return list(self.load_as_dataframe().columns)
-
-    def load_as_anndata(self, columns: Collection[str] | None = None) -> AnnData:
-        """Load the metadata in the store."""
-        anndata = custom_read_zarr(self._group_handler._group)
-        if columns is not None:
-            raise NotImplementedError(
-                "Selecting columns is not implemented for AnnData."
-            )
-        return anndata
-
-    def load_as_dataframe(self, columns: Collection[str] | None = None) -> DataFrame:
-        """List all labels in the group."""
-        dataframe = anndata_to_dataframe(
-            self.load_as_anndata(),
-            index_key=self._index_key,
-            index_type=self._index_type,
-        )
-        if columns is not None:
-            dataframe = dataframe[columns]
-        return dataframe
-
-    def write_from_dataframe(
-        self, table: DataFrame, metadata: dict | None = None
-    ) -> None:
-        """Consolidate the metadata in the store."""
-        anndata = dataframe_to_anndata(table, index_key=self._index_key)
-        self.write_from_anndata(anndata, metadata)
-
-    def write_from_anndata(self, table: AnnData, metadata: dict | None = None) -> None:
-        """Consolidate the metadata in the store."""
-        store = self._group_handler.store
-        if not isinstance(store, str | Path):
-            raise ValueError(
-                "To write an AnnData object the store must be a local path/str."
-            )
-
-        store = Path(store) / self._group_handler.group.path
-        table.write_zarr(store)
-        if metadata is not None:
-            self._group_handler.write_attrs(metadata)

ngio/tables/backends/_json_v1.py

@@ -1,56 +0,0 @@
-from collections.abc import Collection
-
-import pandas as pd
-from pandas import DataFrame
-
-from ngio.tables.backends._abstract_backend import AbstractTableBackend
-from ngio.utils import NgioFileNotFoundError
-
-
-class JsonTableBackend(AbstractTableBackend):
-    """A class to load and write small tables in the zarr group .attrs (json)."""
-
-    @staticmethod
-    def backend_name() -> str:
-        """The name of the backend."""
-        return "json_v1"
-
-    @staticmethod
-    def implements_anndata() -> bool:
-        """Whether the handler implements the anndata protocol."""
-        return False
-
-    @staticmethod
-    def implements_dataframe() -> bool:
-        """Whether the handler implements the dataframe protocol."""
-        return True
-
-    def load_columns(self) -> list[str]:
-        """List all labels in the group."""
-        return list(self.load_as_dataframe().columns)
-
-    def _get_table_group(self):
-        try:
-            table_group = self._group_handler.get_group(path="table")
-        except NgioFileNotFoundError:
-            table_group = self._group_handler.group.create_group("table")
-        return table_group
-
-    def load_as_dataframe(self, columns: Collection[str] | None = None) -> DataFrame:
-        """List all labels in the group."""
-        table_group = self._get_table_group()
-        table_dict = dict(table_group.attrs)
-        data_frame = pd.DataFrame.from_dict(table_dict)
-        if columns is not None:
-            data_frame = data_frame[columns]
-        return data_frame
-
-    def write_from_dataframe(
-        self, table: DataFrame, metadata: dict | None = None
-    ) -> None:
-        """Consolidate the metadata in the store."""
-        table_group = self._get_table_group()
-        table_group.attrs.clear()
-        table_group.attrs.update(table.to_dict())
-        if metadata is not None:
-            self._group_handler.write_attrs(metadata)