ngio 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

ngio/resources/__init__.py

@@ -0,0 +1,55 @@
+"""Predefined resources for testing and demonstration purposes."""
+
+from pathlib import Path
+from typing import Literal
+
+from ngio.resources.resource_model import LabelsInfo, SampleInfo
+
+resources = Path(__file__).parent.resolve()
+
+_resources = {
+    "Cardiomyocyte": SampleInfo(
+        img_path=resources
+        / "20200812-CardiomyocyteDifferentiation14-Cycle1_B03"
+        / "raw.jpg",
+        labels=[
+            LabelsInfo(
+                name="nuclei",
+                label_path=resources
+                / "20200812-CardiomyocyteDifferentiation14-Cycle1_B03"
+                / "nuclei.png",
+                create_masking_table=False,
+                ensure_unique_labels=True,
+            ),
+            LabelsInfo(
+                name="nuclei_mask",
+                label_path=resources
+                / "20200812-CardiomyocyteDifferentiation14-Cycle1_B03"
+                / "mask.png",
+                create_masking_table=True,
+                ensure_unique_labels=False,
+                dtype="uint8",
+            ),
+        ],
+        xy_pixelsize=0.325,
+        z_spacing=1.0,
+        time_spacing=1.0,
+        name="Cardiomyocyte Differentiation",
+        info="20200812-CardiomyocyteDifferentiation14-Cycle1_B03",
+    )
+}
+
+AVAILABLE_SAMPLES = Literal["Cardiomyocyte"]
+
+
+def get_sample_info(name: AVAILABLE_SAMPLES) -> SampleInfo:
+    """Get a predefined resource by name."""
+    image_info = _resources.get(name)
+    if image_info is None:
+        raise ValueError(
+            f"Sample '{name}' not found. Available samples: {_resources.keys()}"
+        )
+    return image_info
+
+
+__all__ = ["AVAILABLE_SAMPLES", "LabelsInfo", "SampleInfo"]

ngio/resources/resource_model.py

@@ -0,0 +1,36 @@
+"""Models for programmatic description of image resources."""
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from ngio.ome_zarr_meta.ngio_specs import (
+    DefaultSpaceUnit,
+    DefaultTimeUnit,
+    SpaceUnits,
+    TimeUnits,
+)
+
+
+class LabelsInfo(BaseModel):
+    """Metadata for a label image."""
+
+    name: str
+    label_path: Path
+    ensure_unique_labels: bool = True
+    create_masking_table: bool = False
+    dtype: str = "uint32"
+
+
+class SampleInfo(BaseModel):
+    """Metadata necessary to create an OME-Ngff from image files."""
+
+    img_path: Path
+    labels: list[LabelsInfo] = Field(default_factory=list)
+    xy_pixelsize: float
+    z_spacing: float = 1.0
+    time_spacing: float = 1.0
+    space_unit: SpaceUnits = DefaultSpaceUnit
+    time_unit: TimeUnits = DefaultTimeUnit
+    name: str | None = None
+    info: str | None = None

ngio/tables/backends/_abstract_backend.py

@@ -210,7 +210,6 @@ class AbstractTableBackend(ABC):
         self,
         table_data: TabularData,
         metadata: dict | None = None,
-        mode: Literal["pandas", "anndata", "polars"] | None = None,
     ) -> None:
         """Serialize the table to the store, and write the metadata.
 
@@ -218,11 +217,11 @@ class AbstractTableBackend(ABC):
         Based on the explicit mode or the type of the table,
         it will call the appropriate write method.
         """
-        if mode == "pandas" or isinstance(table_data, DataFrame):
-            self.write_from_pandas(table_data)  # type: ignore[arg-type]
-        elif mode == "anndata" or isinstance(table_data, AnnData):
-            self.write_from_anndata(table_data)  # type: ignore[arg-type]
-        elif mode == "polars" or isinstance(table_data, PolarsDataFrame | LazyFrame):
+        if isinstance(table_data, DataFrame):
+            self.write_from_pandas(table_data)
+        elif isinstance(table_data, AnnData):
+            self.write_from_anndata(table_data)
+        elif isinstance(table_data, PolarsDataFrame | LazyFrame):
             self.write_from_polars(table_data)
         else:
             raise NgioValueError(

ngio/tables/backends/_anndata.py

@@ -58,7 +58,7 @@ class AnnDataBackend(AbstractTableBackend):
                 "Please make sure to use a compatible "
                 "store like a zarr.DirectoryStore."
             )
-        table.write_zarr(full_url)  # type: ignore
+        table.write_zarr(full_url)  # type: ignore (AnnData writer requires a str path)
 
     def write_from_pandas(self, table: DataFrame) -> None:
         """Serialize the table from a pandas DataFrame."""
@@ -77,7 +77,6 @@ class AnnDataBackend(AbstractTableBackend):
         self.write_from_anndata(anndata)
 
 
-
 class AnnDataBackendV1(AnnDataBackend):
     """A wrapper for the AnnData backend that for backwards compatibility."""
 

ngio/tables/backends/_anndata_utils.py

@@ -17,11 +17,11 @@ from ngio.utils import (
 )
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Collection
+    from collections.abc import Callable, Sequence
 
 
 def custom_anndata_read_zarr(
-    store: StoreOrGroup, elem_to_read: Collection[str] | None = None
+    store: StoreOrGroup, elem_to_read: Sequence[str] | None = None
 ) -> AnnData:
     """Read from a hierarchical Zarr array store.
 
@@ -31,7 +31,7 @@ def custom_anndata_read_zarr(
 
     Args:
         store (StoreOrGroup): A store or group to read the AnnData from.
-        elem_to_read (Collection[str] | None): The elements to read from the store.
+        elem_to_read (Sequence[str] | None): The elements to read from the store.
     """
     group = open_group_wrapper(store=store, mode="r")
 

ngio/tables/backends/_non_zarr_backends.py

@@ -80,7 +80,7 @@ class NonZarrBaseBackend(AbstractTableBackend):
         """Load the table from an FS store."""
         full_url = self._group_handler.full_url
         parquet_path = f"{full_url}/{self.table_name}"
-        store_fs = self._group_handler.store.fs  # type: ignore
+        store_fs = self._group_handler.store.fs  # type: ignore (in this context, store_fs is a fs.FSStore)
         with store_fs.open(parquet_path, "rb") as f:
             dataframe = reader(f)
         return dataframe

ngio/tables/backends/_table_backends.py

@@ -127,7 +127,6 @@ class TableBackendProtocol(Protocol):
         self,
         table_data: DataFrame | AnnData | PolarsDataFrame | LazyFrame,
         metadata: dict[str, str] | None = None,
-        mode: Literal["pandas", "anndata", "polars"] | None = None,
     ) -> None:
         """This is a generic write method.
 

ngio/tables/backends/_utils.py

@@ -126,10 +126,10 @@ def _check_for_mixed_types(series: pd.Series) -> None:
     Raises:
         NgioTableValidationError: If the column has mixed types.
     """
-    if series.apply(type).nunique() > 1:  # type: ignore
+    if series.apply(type).nunique() > 1:  # type: ignore (type lint fails here)
         raise NgioTableValidationError(
             f"Column {series.name} has mixed types: "
-            f"{series.apply(type).unique()}. "  # type: ignore
+            f"{series.apply(type).unique()}. "  # type: ignore (type lint fails here)
             "Type of all elements must be the same."
         )
 
@@ -186,7 +186,7 @@ def normalize_pandas_df(
     pandas_df = _validate_index_key_df(pandas_df, index_key)
     pandas_df = _validate_cast_index_dtype_df(pandas_df, index_type)
     if pandas_df.index.name is not None:
-        index_key = pandas_df.index.name
+        index_key = str(pandas_df.index.name)
 
     if reset_index and pandas_df.index.name is not None:
         pandas_df = pandas_df.reset_index()

ngio/tables/v1/_roi_table.py

@@ -4,10 +4,9 @@ This class follows the roi_table specification at:
 https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/
 """
 
-# Import _type to avoid name conflict with table.type
 from collections.abc import Iterable
-from functools import cache
 from typing import Literal
+from uuid import uuid4
 
 import pandas as pd
 from pydantic import BaseModel
@@ -27,7 +26,7 @@ from ngio.utils import (
     NgioTableValidationError,
     NgioValueError,
     ZarrGroupHandler,
-    ngio_logger,
+    ngio_warn,
 )
 
 REQUIRED_COLUMNS = [
@@ -44,6 +43,11 @@ REQUIRED_COLUMNS = [
 # only a warning is raised if non optional columns are present
 #####################
 
+TIME_COLUMNS = [
+    "t_second",
+    "len_t_second",
+]
+
 ORIGIN_COLUMNS = [
     "x_micrometer_original",
     "y_micrometer_original",
@@ -70,24 +74,17 @@ INDEX_COLUMNS = [
 OPTIONAL_COLUMNS = ORIGIN_COLUMNS + TRANSLATION_COLUMNS + PLATE_COLUMNS + INDEX_COLUMNS
 
 
-@cache
 def _check_optional_columns(col_name: str) -> None:
     """Check if the column name is in the optional columns."""
-    if col_name not in OPTIONAL_COLUMNS:
-        ngio_logger.warning(
-            f"Column {col_name} is not in the optional columns. "
-            f"Standard optional columns are: {OPTIONAL_COLUMNS}."
-        )
+    if col_name not in OPTIONAL_COLUMNS + TIME_COLUMNS:
+        ngio_warn(f"Column {col_name} is not in the optional columns.")
 
 
 def _dataframe_to_rois(
     dataframe: pd.DataFrame,
-    required_columns: list[str] | None = None,
+    required_columns: list[str] = REQUIRED_COLUMNS,
 ) -> dict[str, Roi]:
     """Convert a DataFrame to a WorldCooROI object."""
-    if required_columns is None:
-        required_columns = REQUIRED_COLUMNS
-
     # Validate the columns of the DataFrame
     _required_columns = set(dataframe.columns).intersection(set(required_columns))
     if len(_required_columns) != len(required_columns):
@@ -95,11 +92,15 @@ def _dataframe_to_rois(
             f"Could not find required columns: {_required_columns} in the table."
         )
 
-    extra_columns = set(dataframe.columns).difference(set(required_columns))
+    extra_columns = set(dataframe.columns).difference(
+        set(required_columns + TIME_COLUMNS)
+    )
 
     for col in extra_columns:
         _check_optional_columns(col)
 
+    label_is_index = True if dataframe.index.name == "label" else False
+
     extras = {}
 
     rois = {}
@@ -108,85 +109,173 @@ def _dataframe_to_rois(
         if len(extra_columns) > 0:
             extras = {col: getattr(row, col, None) for col in extra_columns}
 
+        z_micrometer = getattr(row, "z_micrometer", None)
+        z_length_micrometer = getattr(row, "len_z_micrometer", None)
+
+        t_second = getattr(row, "t_second", None)
+        t_length_second = getattr(row, "len_t_second", None)
+
+        if label_is_index:
+            label = int(row.Index)  # type: ignore (type can not be known here, but should be castable to int)
+        else:
+            label = getattr(row, "label", None)
+
         roi = Roi(
             name=str(row.Index),
-            x=row.x_micrometer,  # type: ignore
-            y=row.y_micrometer,  # type: ignore
-            z=row.z_micrometer,  # type: ignore
-            x_length=row.len_x_micrometer,  # type: ignore
-            y_length=row.len_y_micrometer,  # type: ignore
-            z_length=row.len_z_micrometer,  # type: ignore
-            unit="micrometer",  # type: ignore
+            x=row.x_micrometer,  # type: ignore (type can not be known here)
+            y=row.y_micrometer,  # type: ignore (type can not be known here)
+            z=z_micrometer,
+            t=t_second,
+            x_length=row.len_x_micrometer,  # type: ignore (type can not be known here)
+            y_length=row.len_y_micrometer,  # type: ignore (type can not be known here)
+            z_length=z_length_micrometer,
+            t_length=t_length_second,
+            unit="micrometer",
+            label=label,
             **extras,
         )
         rois[roi.name] = roi
     return rois
 
 
-def _table_to_rois(
-    table: TabularData,
-    index_key: str | None = None,
-    index_type: Literal["int", "str"] | None = None,
-    required_columns: list[str] | None = None,
-) -> tuple[pd.DataFrame, dict[str, Roi]]:
-    """Convert a table to a dictionary of ROIs.
-
-    Args:
-        table: The table to convert.
-        index_key: The column name to use as the index of the DataFrame.
-        index_type: The type of the index column in the DataFrame.
-        required_columns: The required columns in the DataFrame.
-
-    Returns:
-        A dictionary of ROIs.
-    """
-    dataframe = convert_to_pandas(
-        table,
-        index_key=index_key,
-        index_type=index_type,
-    )
-    return dataframe, _dataframe_to_rois(dataframe, required_columns=required_columns)
-
-
 def _rois_to_dataframe(rois: dict[str, Roi], index_key: str | None) -> pd.DataFrame:
     """Convert a list of WorldCooROI objects to a DataFrame."""
     data = []
     for roi in rois.values():
+        # This normalization is necessary for backward compatibility
+        z_micrometer = roi.z if roi.z is not None else 0.0
+        len_z_micrometer = roi.z_length if roi.z_length is not None else 1.0
+
         row = {
-            index_key: roi.name,
+            index_key: roi.get_name(),
             "x_micrometer": roi.x,
             "y_micrometer": roi.y,
-            "z_micrometer": roi.z,
+            "z_micrometer": z_micrometer,
             "len_x_micrometer": roi.x_length,
             "len_y_micrometer": roi.y_length,
-            "len_z_micrometer": roi.z_length,
+            "len_z_micrometer": len_z_micrometer,
         }
 
+        if roi.t is not None:
+            row["t_second"] = roi.t
+
+        if roi.t_length is not None:
+            row["len_t_second"] = roi.t_length
+
+        if roi.label is not None and index_key != "label":
+            row["label"] = roi.label
+
         extra = roi.model_extra or {}
         for col in extra:
             _check_optional_columns(col)
             row[col] = extra[col]
         data.append(row)
+
     dataframe = pd.DataFrame(data)
     dataframe = normalize_pandas_df(dataframe, index_key=index_key)
     return dataframe
 
 
+class RoiDictWrapper:
+    """A wrapper for a dictionary of ROIs to provide a consistent interface."""
+
+    def __init__(self, rois: Iterable[Roi]) -> None:
+        self._rois_by_name = {}
+        self._rois_by_label = {}
+        for roi in rois:
+            name = roi.get_name()
+            if name in self._rois_by_name:
+                name = f"{name}_{uuid4().hex[:8]}"
+            self._rois_by_name[name] = roi
+            if roi.label is not None:
+                self._rois_by_label[roi.label] = roi
+
+    def get_by_name(self, name: str, default: Roi | None = None) -> Roi | None:
+        """Get an ROI by its name."""
+        return self._rois_by_name.get(name, default)
+
+    def get_by_label(self, label: int, default: Roi | None = None) -> Roi | None:
+        """Get an ROI by its label."""
+        return self._rois_by_label.get(label, default)
+
+    def _add_roi(self, roi: Roi, overwrite: bool = False) -> None:
+        """Add an ROI to the wrapper."""
+        if roi.name in self._rois_by_name and not overwrite:
+            raise NgioValueError(f"ROI with name {roi.name} already exists.")
+
+        self._rois_by_name[roi.name] = roi
+        if roi.label is not None:
+            self._rois_by_label[roi.label] = roi
+
+    def add_rois(self, rois: Roi | Iterable[Roi], overwrite: bool = False) -> None:
+        """Add ROIs to the wrapper."""
+        if isinstance(rois, Roi):
+            rois = [rois]
+
+        for roi in rois:
+            self._add_roi(roi, overwrite=overwrite)
+
+    def to_list(self) -> list[Roi]:
+        """Return the list of ROIs."""
+        return list(self._rois_by_name.values())
+
+    def to_dataframe(self, index_key: str | None = None) -> pd.DataFrame:
+        """Convert the ROIs to a DataFrame."""
+        return _rois_to_dataframe(self._rois_by_name, index_key=index_key)
+
+    @classmethod
+    def from_dataframe(
+        cls, dataframe: pd.DataFrame, required_columns: list[str] = REQUIRED_COLUMNS
+    ) -> "RoiDictWrapper":
+        """Create a RoiDictWrapper from a DataFrame."""
+        rois = _dataframe_to_rois(dataframe, required_columns=required_columns)
+        return cls(rois.values())
+
+
+def _table_to_rois(
+    table: TabularData,
+    index_key: str | None = None,
+    index_type: Literal["int", "str"] | None = None,
+    required_columns: list[str] = REQUIRED_COLUMNS,
+) -> tuple[pd.DataFrame, RoiDictWrapper]:
+    """Convert a table to a dictionary of ROIs.
+
+    Args:
+        table: The table to convert.
+        index_key: The column name to use as the index of the DataFrame.
+        index_type: The type of the index column in the DataFrame.
+        required_columns: The required columns in the DataFrame.
+
+    Returns:
+        A tuple containing the DataFrame and a RoiDictWrapper with the ROIs.
+    """
+    dataframe = convert_to_pandas(
+        table,
+        index_key=index_key,
+        index_type=index_type,
+    )
+    roi_dict_wrapper = RoiDictWrapper.from_dataframe(
+        dataframe, required_columns=required_columns
+    )
+    return dataframe, roi_dict_wrapper
+
+
 class GenericRoiTableV1(AbstractBaseTable):
     def __init__(
         self,
         *,
         rois: Iterable[Roi] | None = None,
         meta: BackendMeta,
+        required_columns: list[str] = REQUIRED_COLUMNS,
     ) -> None:
         table = None
 
-        self._rois: dict[str, Roi] | None = None
+        self._rois: RoiDictWrapper | None = None
         if rois is not None:
-            self._rois = {}
-            self.add(rois)
-            table = _rois_to_dataframe(self._rois, index_key=meta.index_key)
+            self._rois = RoiDictWrapper(rois)
+            table = self._rois.to_dataframe(index_key=meta.index_key)
 
+        self._required_columns = required_columns
         super().__init__(table_data=table, meta=meta)
 
     def __repr__(self) -> str:
@@ -213,7 +302,7 @@ class GenericRoiTableV1(AbstractBaseTable):
             return super().table_data
 
         if len(self.rois()) > 0:
-            self._table_data = _rois_to_dataframe(self._rois, index_key=self.index_key)
+            self._table_data = self._rois.to_dataframe(index_key=self.meta.index_key)
         return super().table_data
 
     def set_table_data(
@@ -260,14 +349,16 @@ class GenericRoiTableV1(AbstractBaseTable):
         If the ROIs are not loaded, load them from the table.
         """
         if self._rois is None:
-            self._rois = _dataframe_to_rois(self.dataframe)
+            self._rois = RoiDictWrapper.from_dataframe(
+                self.dataframe, required_columns=self._required_columns
+            )
 
     def rois(self) -> list[Roi]:
         """List all ROIs in the table."""
         self._check_rois()
         if self._rois is None:
             return []
-        return list(self._rois.values())
+        return self._rois.to_list()
 
     def add(self, roi: Roi | Iterable[Roi], overwrite: bool = False) -> None:
         """Append ROIs to the current table.
@@ -281,22 +372,20 @@ class GenericRoiTableV1(AbstractBaseTable):
 
         self._check_rois()
         if self._rois is None:
-            self._rois = {}
+            self._rois = RoiDictWrapper([])
 
-        for _roi in roi:
-            if not overwrite and _roi.name in self._rois:
-                raise NgioValueError(f"ROI {_roi.name} already exists in the table.")
-            self._rois[_roi.name] = _roi
+        self._rois.add_rois(roi, overwrite=overwrite)
 
     def get(self, roi_name: str) -> Roi:
         """Get an ROI from the table."""
         self._check_rois()
         if self._rois is None:
-            self._rois = {}
+            self._rois = RoiDictWrapper([])
 
-        if roi_name not in self._rois:
-            raise NgioValueError(f"ROI {roi_name} not found in the table.")
-        return self._rois[roi_name]
+        roi = self._rois.get_by_name(roi_name)
+        if roi is None:
+            raise NgioValueError(f"ROI with name {roi_name} not found in the table.")
+        return roi
 
     @classmethod
     def from_table_data(
@@ -309,7 +398,7 @@ class GenericRoiTableV1(AbstractBaseTable):
             index_type=meta.index_type,
             required_columns=REQUIRED_COLUMNS,
         )
-        return cls(rois=rois.values(), meta=meta)
+        return cls(rois=rois.to_list(), meta=meta)
 
 
 class RoiTableV1Meta(BackendMeta):
@@ -457,7 +546,13 @@ class MaskingRoiTableV1(GenericRoiTableV1):
         path = path.split("/")[-1]
         return path
 
-    def get(self, label: int | str) -> Roi:  # type: ignore
-        """Get an ROI from the table."""
-        roi_name = str(label)
-        return super().get(roi_name)
+    def get_label(self, label: int) -> Roi:
+        """Get an ROI by label."""
+        self._check_rois()
+        if self._rois is None:
+            self._rois = RoiDictWrapper([])
+        roi = self._rois.get_by_label(label)
+
+        if roi is None:
+            raise NgioValueError(f"ROI with label {label} not found.")
+        return roi

ngio/transforms/__init__.py

@@ -0,0 +1,5 @@
+"""Concrete IO transformations."""
+
+from ngio.transforms._zoom import ZoomTransform
+
+__all__ = ["ZoomTransform"]

ngio/transforms/_zoom.py

@@ -0,0 +1,19 @@
+from ngio.common._zoom import (
+    InterpolationOrder,
+)
+from ngio.images._abstract_image import AbstractImage
+from ngio.io_pipes._zoom_transform import BaseZoomTransform
+
+
+class ZoomTransform(BaseZoomTransform):
+    def __init__(
+        self,
+        input_image: AbstractImage,
+        target_image: AbstractImage,
+        order: InterpolationOrder = "nearest",
+    ) -> None:
+        super().__init__(
+            input_dimensions=input_image.dimensions,
+            target_dimensions=target_image.dimensions,
+            order=order,
+        )

ngio/utils/__init__.py

@@ -2,7 +2,6 @@
 
 import os
 
-from ngio.common._common_types import ArrayLike
 from ngio.utils._datasets import (
     download_ome_zarr_dataset,
     list_ome_zarr_datasets,
@@ -16,7 +15,7 @@ from ngio.utils._errors import (
     NgioValueError,
 )
 from ngio.utils._fractal_fsspec_store import fractal_fsspec_store
-from ngio.utils._logger import ngio_logger, set_logger_level
+from ngio.utils._logger import ngio_logger, ngio_warn, set_logger_level
 from ngio.utils._zarr_utils import (
     AccessModeLiteral,
     StoreOrGroup,
@@ -29,7 +28,6 @@ set_logger_level(os.getenv("NGIO_LOGGER_LEVEL", "WARNING"))
 __all__ = [
     # Zarr
     "AccessModeLiteral",
-    "ArrayLike",
     # Errors
     "NgioFileExistsError",
     "NgioFileNotFoundError",
@@ -44,6 +42,7 @@ __all__ = [
     "list_ome_zarr_datasets",
     # Logger
     "ngio_logger",
+    "ngio_warn",
     "open_group_wrapper",
     "print_datasets_infos",
     "set_logger_level",

ngio/utils/_datasets.py

@@ -38,6 +38,11 @@ class UnzipAndRename(pooch.Unzip):
             return None
 
         tmp_dir = Path(extract_dir) / "tmp"
+        # If tmp_dir exists, remove it
+        if tmp_dir.exists():
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+
         super()._extract_file(fname, tmp_dir)
 
         list_extracted_dirs = tmp_dir.iterdir()

ngio/utils/_logger.py

@@ -1,4 +1,6 @@
 import logging
+import time
+from functools import cache
 
 from ngio.utils._errors import NgioValueError
 
@@ -29,3 +31,20 @@ def set_logger_level(level: str) -> None:
         raise NgioValueError(f"Invalid log level: {level}")
 
     ngio_logger.setLevel(level)
+
+
+@cache
+def _warn(message: str, ttl_hash: int) -> None:
+    """Log a warning message with a time-to-live (TTL) hash."""
+    ngio_logger.warning(message, stacklevel=3)
+
+
+def ngio_warn(message: str, cooldown: int = 2) -> None:
+    """Log a warning message.
+
+    Args:
+        message: The warning message to log.
+        cooldown: The cooldown period in seconds to avoid repeated logging.
+    """
+    ttl_hash = time.time() // cooldown
+    _warn(message, ttl_hash)