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

ngio/ome_zarr_meta/v04/_v04_spec_utils.py

@@ -0,0 +1,412 @@
+"""Utilities for OME-Zarr v04 specs.
+
+This module provides a set of classes to internally handle the metadata
+of the OME-Zarr v04 specification.
+
+For Images and Labels implements the following functionalities:
+- A function to find if a dict view of the metadata is a valid OME-Zarr v04 metadata.
+- A function to convert a v04 image metadata to a ngio image metadata.
+- A function to convert a ngio image metadata to a v04 image metadata.
+"""
+
+from ome_zarr_models.common.multiscales import ValidTransform as ValidTransformV04
+from ome_zarr_models.v04.axes import Axis as AxisV04
+from ome_zarr_models.v04.coordinate_transformations import VectorScale as VectorScaleV04
+from ome_zarr_models.v04.coordinate_transformations import (
+    VectorTranslation as VectorTranslationV04,
+)
+from ome_zarr_models.v04.image import ImageAttrs as ImageAttrsV04
+from ome_zarr_models.v04.image_label import ImageLabelAttrs as LabelAttrsV04
+from ome_zarr_models.v04.multiscales import Dataset as DatasetV04
+from ome_zarr_models.v04.multiscales import Multiscale as MultiscaleV04
+from ome_zarr_models.v04.omero import Channel as ChannelV04
+from ome_zarr_models.v04.omero import Omero as OmeroV04
+from ome_zarr_models.v04.omero import Window as WindowV04
+from pydantic import ValidationError
+
+from ngio.ome_zarr_meta.ngio_specs import (
+    AxesSetup,
+    Axis,
+    AxisType,
+    Channel,
+    ChannelsMeta,
+    ChannelVisualisation,
+    Dataset,
+    ImageLabelSource,
+    NgioImageMeta,
+    NgioLabelMeta,
+    default_channel_name,
+)
+from ngio.ome_zarr_meta.ngio_specs._ngio_image import NgffVersion
+
+
+def _is_v04_image_meta(metadata: dict) -> ImageAttrsV04 | ValidationError:
+    """Check if the metadata is a valid OME-Zarr v04 metadata.
+
+    Args:
+        metadata (dict): The metadata to check.
+
+    Returns:
+        bool: True if the metadata is a valid OME-Zarr v04 metadata, False otherwise.
+    """
+    try:
+        return ImageAttrsV04(**metadata)
+    except ValidationError as e:
+        return e
+
+
+def _is_v04_label_meta(metadata: dict) -> LabelAttrsV04 | ValidationError:
+    """Check if the metadata is a valid OME-Zarr v04 metadata.
+
+    Args:
+        metadata (dict): The metadata to check.
+
+    Returns:
+        bool: True if the metadata is a valid OME-Zarr v04 metadata, False otherwise.
+    """
+    try:
+        return LabelAttrsV04(**metadata)
+    except ValidationError as e:
+        return e
+    raise RuntimeError("Unreachable code")
+
+
+def _v04_omero_to_channels(v04_omero: OmeroV04 | None) -> ChannelsMeta | None:
+    if v04_omero is None:
+        return None
+
+    ngio_channels = []
+    for idx, v04_channel in enumerate(v04_omero.channels):
+        channel_extra = v04_channel.model_extra
+
+        if channel_extra is None:
+            channel_extra = {}
+
+        if "label" in channel_extra:
+            label = channel_extra.pop("label")
+        else:
+            label = default_channel_name(idx)
+
+        if "wavelength_id" in channel_extra:
+            wavelength_id = channel_extra.pop("wavelength_id")
+        else:
+            wavelength_id = label
+
+        if "active" in channel_extra:
+            active = channel_extra.pop("active")
+        else:
+            active = True
+
+        channel_visualisation = ChannelVisualisation(
+            color=v04_channel.color,
+            start=v04_channel.window.start,
+            end=v04_channel.window.end,
+            min=v04_channel.window.min,
+            max=v04_channel.window.max,
+            active=active,
+            **channel_extra,
+        )
+
+        ngio_channels.append(
+            Channel(
+                label=label,
+                wavelength_id=wavelength_id,
+                channel_visualisation=channel_visualisation,
+            )
+        )
+
+    v04_omero_extra = v04_omero.model_extra if v04_omero.model_extra is not None else {}
+    return ChannelsMeta(channels=ngio_channels, **v04_omero_extra)
+
+
+def _compute_scale_translation(
+    v04_transforms: ValidTransformV04,
+    scale: list[float],
+    translation: list[float],
+) -> tuple[list[float], list[float]]:
+    for v04_transform in v04_transforms:
+        if isinstance(v04_transform, VectorScaleV04):
+            scale = [t1 * t2 for t1, t2 in zip(scale, v04_transform.scale, strict=True)]
+
+        elif isinstance(v04_transform, VectorTranslationV04):
+            translation = [
+                t1 + t2
+                for t1, t2 in zip(translation, v04_transform.translation, strict=True)
+            ]
+        else:
+            raise NotImplementedError(
+                f"Coordinate transformation {v04_transform} is not supported."
+            )
+    return scale, translation
+
+
+def _v04_to_ngio_datasets(
+    v04_multiscale: MultiscaleV04,
+    axes_setup: AxesSetup,
+    allow_non_canonical_axes: bool = False,
+    strict_canonical_order: bool = True,
+) -> list[Dataset]:
+    """Convert a v04 multiscale to a list of ngio datasets."""
+    datasets = []
+
+    global_scale = [1.0] * len(v04_multiscale.axes)
+    global_translation = [0.0] * len(v04_multiscale.axes)
+
+    if v04_multiscale.coordinateTransformations is not None:
+        global_scale, global_translation = _compute_scale_translation(
+            v04_multiscale.coordinateTransformations, global_scale, global_translation
+        )
+
+    for v04_dataset in v04_multiscale.datasets:
+        axes = []
+        for v04_axis in v04_multiscale.axes:
+            unit = v04_axis.unit
+            if unit is not None and not isinstance(unit, str):
+                unit = str(unit)
+            axes.append(
+                Axis(
+                    on_disk_name=v04_axis.name,
+                    axis_type=AxisType(v04_axis.type),
+                    # (for some reason the type is a generic JsonValue,
+                    # but it should be a string or None)
+                    unit=v04_axis.unit,  # type: ignore
+                )
+            )
+
+        _on_disk_scale, _on_disk_translation = _compute_scale_translation(
+            v04_dataset.coordinateTransformations, global_scale, global_translation
+        )
+        datasets.append(
+            Dataset(
+                path=v04_dataset.path,
+                on_disk_axes=axes,
+                on_disk_scale=_on_disk_scale,
+                on_disk_translation=_on_disk_translation,
+                axes_setup=axes_setup,
+                allow_non_canonical_axes=allow_non_canonical_axes,
+                strict_canonical_order=strict_canonical_order,
+            )
+        )
+    return datasets
+
+
+def v04_to_ngio_image_meta(
+    metadata: dict,
+    axes_setup: AxesSetup | None = None,
+    allow_non_canonical_axes: bool = False,
+    strict_canonical_order: bool = True,
+) -> tuple[bool, NgioImageMeta | ValidationError]:
+    """Convert a v04 image metadata to a ngio image metadata.
+
+    Args:
+        metadata (dict): The v04 image metadata.
+        axes_setup (AxesSetup, optional): The axes setup. This is
+            required to convert image with non-canonical axes names.
+        allow_non_canonical_axes (bool, optional): Allow non-canonical axes.
+        strict_canonical_order (bool, optional): Strict canonical order.
+
+    Returns:
+        NgioImageMeta: The ngio image metadata.
+    """
+    v04_image = _is_v04_image_meta(metadata)
+    if isinstance(v04_image, ValidationError):
+        return False, v04_image
+
+    if len(v04_image.multiscales) > 1:
+        raise NotImplementedError(
+            "Multiple multiscales in a single image are not supported in ngio."
+        )
+
+    v04_muliscale = v04_image.multiscales[0]
+
+    channels_meta = _v04_omero_to_channels(v04_image.omero)
+    axes_setup = axes_setup if axes_setup is not None else AxesSetup()
+    datasets = _v04_to_ngio_datasets(
+        v04_muliscale,
+        axes_setup=axes_setup,
+        allow_non_canonical_axes=allow_non_canonical_axes,
+        strict_canonical_order=strict_canonical_order,
+    )
+
+    name = v04_muliscale.name
+    if name is not None and not isinstance(name, str):
+        name = str(name)
+    return True, NgioImageMeta(
+        version="0.4",
+        name=name,
+        datasets=datasets,
+        channels=channels_meta,
+    )
+
+
+def v04_to_ngio_label_meta(
+    metadata: dict,
+    axes_setup: AxesSetup | None = None,
+    allow_non_canonical_axes: bool = False,
+    strict_canonical_order: bool = True,
+) -> tuple[bool, NgioLabelMeta | ValidationError]:
+    """Convert a v04 image metadata to a ngio image metadata.
+
+    Args:
+        metadata (dict): The v04 image metadata.
+        axes_setup (AxesSetup, optional): The axes setup. This is
+            required to convert image with non-canonical axes names.
+        allow_non_canonical_axes (bool, optional): Allow non-canonical axes.
+        strict_canonical_order (bool, optional): Strict canonical order.
+
+    Returns:
+        NgioImageMeta: The ngio image metadata.
+    """
+    v04_label = _is_v04_label_meta(metadata)
+    if isinstance(v04_label, ValidationError):
+        return False, v04_label
+
+    if len(v04_label.multiscales) > 1:
+        raise NotImplementedError(
+            "Multiple multiscales in a single image are not supported in ngio."
+        )
+
+    v04_muliscale = v04_label.multiscales[0]
+
+    axes_setup = axes_setup if axes_setup is not None else AxesSetup()
+    datasets = _v04_to_ngio_datasets(
+        v04_muliscale,
+        axes_setup=axes_setup,
+        allow_non_canonical_axes=allow_non_canonical_axes,
+        strict_canonical_order=strict_canonical_order,
+    )
+
+    source = v04_label.image_label.source
+    if source is None:
+        image_label_source = None
+    else:
+        source = v04_label.image_label.source
+        if source is None:
+            image_label_source = None
+        else:
+            image_label_source = source.image
+        image_label_source = ImageLabelSource(
+            version=NgffVersion.v04,
+            source={"image": image_label_source},
+        )
+    name = v04_muliscale.name
+    if name is not None and not isinstance(name, str):
+        name = str(name)
+
+    return True, NgioLabelMeta(
+        version="0.4",
+        name=name,
+        datasets=datasets,
+        image_label=image_label_source,
+    )
+
+
+def _ngio_to_v04_multiscale(datasets: list[Dataset]) -> MultiscaleV04:
+    """Convert a ngio multiscale to a v04 multiscale.
+
+    Args:
+        datasets (list[Dataset]): The ngio datasets.
+
+    Returns:
+        MultiscaleV04: The v04 multiscale.
+    """
+    ax_mapper = datasets[0].axes_mapper
+    v04_axes = []
+    for axis in ax_mapper.on_disk_axes:
+        v04_axes.append(
+            AxisV04(
+                name=axis.on_disk_name,
+                type=axis.axis_type.value if axis.axis_type is not None else None,
+                unit=axis.unit.value if axis.unit is not None else None,
+            )
+        )
+
+    v04_datasets = []
+    for dataset in datasets:
+        transform = [VectorScaleV04(type="scale", scale=list(dataset._on_disk_scale))]
+        if sum(dataset._on_disk_translation) > 0:
+            transform = (
+                VectorScaleV04(type="scale", scale=list(dataset._on_disk_scale)),
+                VectorTranslationV04(
+                    type="translation", translation=list(dataset._on_disk_translation)
+                ),
+            )
+        else:
+            transform = (
+                VectorScaleV04(type="scale", scale=list(dataset._on_disk_scale)),
+            )
+
+        v04_datasets.append(
+            DatasetV04(path=dataset.path, coordinateTransformations=transform)
+        )
+    return MultiscaleV04(
+        axes=v04_axes,
+        datasets=tuple(v04_datasets),
+        version="0.4",
+    )
+
+
+def _ngio_to_v04_omero(channels: ChannelsMeta | None) -> OmeroV04 | None:
+    """Convert a ngio channels to a v04 omero."""
+    if channels is None:
+        return None
+
+    v04_channels = []
+    for channel in channels.channels:
+        _model_extra = {
+            "label": channel.label,
+            "wavelength_id": channel.wavelength_id,
+            "active": channel.channel_visualisation.active,
+        }
+        if channel.channel_visualisation.model_extra is not None:
+            _model_extra.update(channel.channel_visualisation.model_extra)
+
+        v04_channels.append(
+            ChannelV04(
+                color=channel.channel_visualisation.valid_color,
+                window=WindowV04(
+                    start=channel.channel_visualisation.start,
+                    end=channel.channel_visualisation.end,
+                    min=channel.channel_visualisation.min,
+                    max=channel.channel_visualisation.max,
+                ),
+                **_model_extra,
+            )
+        )
+
+    _model_extra = channels.model_extra if channels.model_extra is not None else {}
+    return OmeroV04(channels=v04_channels, **_model_extra)
+
+
+def ngio_to_v04_image_meta(metadata: NgioImageMeta) -> dict:
+    """Convert a ngio image metadata to a v04 image metadata.
+
+    Args:
+        metadata (NgioImageMeta): The ngio image metadata.
+
+    Returns:
+        dict: The v04 image metadata.
+    """
+    v04_muliscale = _ngio_to_v04_multiscale(metadata.datasets)
+    v04_omero = _ngio_to_v04_omero(metadata._channels_meta)
+
+    v04_image = ImageAttrsV04(multiscales=[v04_muliscale], omero=v04_omero)
+    return v04_image.model_dump(exclude_none=True)
+
+
+def ngio_to_v04_label_meta(metadata: NgioLabelMeta) -> dict:
+    """Convert a ngio image metadata to a v04 image metadata.
+
+    Args:
+        metadata (NgioImageMeta): The ngio image metadata.
+
+    Returns:
+        dict: The v04 image metadata.
+    """
+    v04_muliscale = _ngio_to_v04_multiscale(metadata.datasets)
+    v04_label = LabelAttrsV04(
+        multiscales=[v04_muliscale],
+        # image_label is aliased as 'imae-label'
+        image_label=metadata.image_label.model_dump(),  # type: ignore
+    )
+    return v04_label.model_dump(exclude_none=True)

ngio/tables/__init__.py

@@ -1,11 +1,27 @@
-"""Module for handling tables in the Fractal format."""
+"""Ngio Tables implementations."""
 
-from ngio.tables.tables_group import (
+from ngio.tables.backends import ImplementedTableBackends
+from ngio.tables.tables_container import (
     FeatureTable,
     MaskingROITable,
-    ROITable,
+    RoiTable,
     Table,
-    TableGroup,
+    TablesContainer,
+    TypedTable,
+    open_table,
+    open_tables_container,
 )
+from ngio.tables.v1._generic_table import GenericTable
 
-__all__ = ["Table", "ROITable", "FeatureTable", "MaskingROITable", "TableGroup"]
+__all__ = [
+    "FeatureTable",
+    "GenericTable",
+    "ImplementedTableBackends",
+    "MaskingROITable",
+    "RoiTable",
+    "Table",
+    "TablesContainer",
+    "TypedTable",
+    "open_table",
+    "open_tables_container",
+]

ngio/tables/_validators.py

@@ -0,0 +1,192 @@
+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/__init__.py

@@ -0,0 +1,8 @@
+"""Ngio Tables backend implementations."""
+
+from ngio.tables.backends._table_backends import (
+    ImplementedTableBackends,
+    TableBackendProtocol,
+)
+
+__all__ = ["ImplementedTableBackends", "TableBackendProtocol"]