ngio 0.2.9__py3-none-any.whl → 0.3.0__py3-none-any.whl

ngio/images/{image.py → _image.py}

@@ -3,11 +3,11 @@
 from collections.abc import Collection
 from typing import Literal
 
-from dask import array as da
+import dask.array as da
 
 from ngio.common import Dimensions
-from ngio.images.abstract_image import AbstractImage, consolidate_image
-from ngio.images.create import create_empty_image_container
+from ngio.images._abstract_image import AbstractImage, consolidate_image
+from ngio.images._create import create_empty_image_container
 from ngio.ome_zarr_meta import (
     ImageMetaHandler,
     NgioImageMeta,
@@ -152,31 +152,33 @@ class ImagesContainer:
 
     def set_channel_meta(
         self,
-        labels: Collection[str] | int | None = None,
-        wavelength_id: Collection[str] | None = None,
-        start: Collection[float] | None = None,
-        end: Collection[float] | None = None,
+        labels: Collection[str | None] | int | None = None,
+        wavelength_id: Collection[str | None] | None = None,
+        start: Collection[float | None] | None = None,
+        end: Collection[float | None] | None = None,
         percentiles: tuple[float, float] | None = None,
-        colors: Collection[str] | None = None,
-        active: Collection[bool] | None = None,
+        colors: Collection[str | None] | None = None,
+        active: Collection[bool | None] | None = None,
         **omero_kwargs: dict,
     ) -> None:
         """Create a ChannelsMeta object with the default unit.
 
         Args:
-            labels(Collection[str] | int): The list of channels names in the image.
-                If an integer is provided, the channels will be named "channel_i".
-            wavelength_id(Collection[str] | None): The wavelength ID of the channel.
+            labels(Collection[str | None] | int): The list of channels names
+                in the image. If an integer is provided, the channels will
+                be named "channel_i".
+            wavelength_id(Collection[str | None]): The wavelength ID of the channel.
                 If None, the wavelength ID will be the same as the channel name.
-            start(Collection[float] | None): The start value for each channel.
+            start(Collection[float | None]): The start value for each channel.
                 If None, the start value will be computed from the image.
-            end(Collection[float] | None): The end value for each channel.
+            end(Collection[float | None]): The end value for each channel.
                 If None, the end value will be computed from the image.
-            percentiles(tuple[float, float] | None): The start and end percentiles
-                for each channel. If None, the percentiles will not be computed.
-            colors(Collection[str, NgioColors] | None): The list of colors for the
+            percentiles(tuple[float, float] | None): The start and end
+                percentiles for each channel. If None, the percentiles will
+                not be computed.
+            colors(Collection[str | None]): The list of colors for the
                 channels. If None, the colors will be random.
-            active (Collection[bool] | None):active(bool): Whether the channel should
+            active (Collection[bool | None]): Whether the channel should
                 be shown by default.
             omero_kwargs(dict): Extra fields to store in the omero attributes.
         """
@@ -376,9 +378,12 @@ def compute_image_percentile(
     starts, ends = [], []
     for c in range(image.num_channels):
         if image.num_channels == 1:
-            data = image.get_array(mode="dask").ravel()
+            data = image.get_array(mode="dask")
         else:
-            data = image.get_array(c=c, mode="dask").ravel()
+            data = image.get_array(c=c, mode="dask")
+
+        assert isinstance(data, da.Array), "Data must be a Dask array."
+        data = da.ravel(data)
         # remove all the zeros
         mask = data > 1e-16
         data = data[mask]
@@ -391,7 +396,7 @@ def compute_image_percentile(
         # compute the percentiles
         _s_perc, _e_perc = da.percentile(
             data, [start_percentile, end_percentile], method="nearest"
-        ).compute()
+        ).compute()  # type: ignore
 
         starts.append(float(_s_perc))
         ends.append(float(_e_perc))

ngio/images/{label.py → _label.py}

@@ -3,10 +3,12 @@
 from collections.abc import Collection
 from typing import Literal
 
+import dask.array as da
+
 from ngio.common import compute_masking_roi
-from ngio.images.abstract_image import AbstractImage, consolidate_image
-from ngio.images.create import create_empty_label_container
-from ngio.images.image import Image
+from ngio.images._abstract_image import AbstractImage, consolidate_image
+from ngio.images._create import create_empty_label_container
+from ngio.images._image import Image
 from ngio.ome_zarr_meta import (
     LabelMetaHandler,
     NgioLabelMeta,
@@ -309,6 +311,6 @@ def build_masking_roi_table(label: Label) -> MaskingRoiTable:
         raise NgioValueError("Time series labels are not supported.")
 
     array = label.get_array(axes_order=["z", "y", "x"], mode="dask")
-
+    assert isinstance(array, da.Array), "Array must be a Dask array."
     rois = compute_masking_roi(array, label.pixel_size)
     return MaskingRoiTable(rois, reference_label=label.meta.name)

ngio/images/{masked_image.py → _masked_image.py}

@@ -4,8 +4,8 @@ from collections.abc import Collection, Iterable
 from typing import Literal
 
 from ngio.common import ArrayLike, get_masked_pipe, roi_to_slice_kwargs, set_masked_pipe
-from ngio.images.image import Image
-from ngio.images.label import Label
+from ngio.images._image import Image
+from ngio.images._label import Label
 from ngio.ome_zarr_meta import ImageMetaHandler, LabelMetaHandler
 from ngio.tables import MaskingRoiTable
 from ngio.utils import (

ngio/images/{ome_zarr_container.py → _ome_zarr_container.py}

@@ -1,14 +1,14 @@
 """Abstract class for handling OME-NGFF images."""
 
+import warnings
 from collections.abc import Collection
-from typing import Literal, overload
 
 import numpy as np
 
-from ngio.images.create import create_empty_image_container
-from ngio.images.image import Image, ImagesContainer
-from ngio.images.label import Label, LabelsContainer
-from ngio.images.masked_image import MaskedImage, MaskedLabel
+from ngio.images._create import create_empty_image_container
+from ngio.images._image import Image, ImagesContainer
+from ngio.images._label import Label, LabelsContainer
+from ngio.images._masked_image import MaskedImage, MaskedLabel
 from ngio.ome_zarr_meta import (
     NgioImageMeta,
     PixelSize,
@@ -22,12 +22,15 @@ from ngio.ome_zarr_meta.ngio_specs import (
     TimeUnits,
 )
 from ngio.tables import (
+    ConditionTable,
     FeatureTable,
     GenericRoiTable,
     MaskingRoiTable,
     RoiTable,
     Table,
+    TableBackend,
     TablesContainer,
+    TableType,
     TypedTable,
 )
 from ngio.utils import (
@@ -65,7 +68,7 @@ class OmeZarrContainer:
         group_handler: ZarrGroupHandler,
         table_container: TablesContainer | None = None,
         label_container: LabelsContainer | None = None,
-        validate_arrays: bool = True,
+        validate_paths: bool = False,
     ) -> None:
         """Initialize the OmeZarrContainer."""
         self._group_handler = group_handler
@@ -74,6 +77,10 @@ class OmeZarrContainer:
         self._labels_container = label_container
         self._tables_container = table_container
 
+        if validate_paths:
+            for level_path in self._images_container.levels_paths:
+                self.get_image(path=level_path)
+
     def __repr__(self) -> str:
         """Return a string representation of the image."""
         num_labels = len(self.list_labels())
@@ -96,24 +103,40 @@ class OmeZarrContainer:
         """Return the image container."""
         return self._images_container
 
-    @property
-    def labels_container(self) -> LabelsContainer:
+    def _get_labels_container(self) -> LabelsContainer | None:
         """Return the labels container."""
         if self._labels_container is None:
-            self._labels_container = _default_label_container(self._group_handler)
-            if self._labels_container is None:
-                raise NgioValidationError("No labels found in the image.")
+            _labels_container = _default_label_container(self._group_handler)
+            if _labels_container is None:
+                return None
+            self._labels_container = _labels_container
         return self._labels_container
 
     @property
-    def tables_container(self) -> TablesContainer:
+    def labels_container(self) -> LabelsContainer:
+        """Return the labels container."""
+        _labels_container = self._get_labels_container()
+        if _labels_container is None:
+            raise NgioValidationError("No labels found in the image.")
+        return _labels_container
+
+    def _get_tables_container(self) -> TablesContainer | None:
         """Return the tables container."""
         if self._tables_container is None:
-            self._tables_container = _default_table_container(self._group_handler)
-            if self._tables_container is None:
-                raise NgioValidationError("No tables found in the image.")
+            _tables_container = _default_table_container(self._group_handler)
+            if _tables_container is None:
+                return None
+            self._tables_container = _tables_container
         return self._tables_container
 
+    @property
+    def tables_container(self) -> TablesContainer:
+        """Return the tables container."""
+        _tables_container = self._get_tables_container()
+        if _tables_container is None:
+            raise NgioValidationError("No tables found in the image.")
+        return _tables_container
+
     @property
     def image_meta(self) -> NgioImageMeta:
         """Return the image metadata."""
@@ -264,9 +287,7 @@ class OmeZarrContainer:
         if masking_table_name is None:
             masking_table = masking_label.build_masking_roi_table()
         else:
-            masking_table = self.get_table(
-                masking_table_name, check_type="masking_roi_table"
-            )
+            masking_table = self.get_masking_roi_table(name=masking_table_name)
 
         return MaskedImage(
             group_handler=image._group_handler,
@@ -331,7 +352,7 @@ class OmeZarrContainer:
 
         new_ome_zarr = OmeZarrContainer(
             group_handler=handler,
-            validate_arrays=False,
+            validate_paths=False,
         )
 
         if copy_labels:
@@ -345,84 +366,128 @@ class OmeZarrContainer:
             )
         return new_ome_zarr
 
-    def list_tables(self) -> list[str]:
+    def list_tables(self, filter_types: TypedTable | str | None = None) -> list[str]:
         """List all tables in the image."""
-        return self.tables_container.list()
+        table_container = self._get_tables_container()
+        if table_container is None:
+            return []
+
+        return table_container.list(
+            filter_types=filter_types,
+        )
 
     def list_roi_tables(self) -> list[str]:
         """List all ROI tables in the image."""
-        return self.tables_container.list_roi_tables()
+        masking_roi = self.tables_container.list(
+            filter_types="masking_roi_table",
+        )
+        roi = self.tables_container.list(
+            filter_types="roi_table",
+        )
+        return masking_roi + roi
 
-    @overload
-    def get_table(self, name: str) -> Table: ...
+    def get_roi_table(self, name: str) -> RoiTable:
+        """Get a ROI table from the image.
 
-    @overload
-    def get_table(self, name: str, check_type: None) -> Table: ...
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, RoiTable):
+            raise NgioValueError(f"Table {name} is not a ROI table. Got {type(table)}")
+        return table
 
-    @overload
-    def get_table(self, name: str, check_type: Literal["roi_table"]) -> RoiTable: ...
+    def get_masking_roi_table(self, name: str) -> MaskingRoiTable:
+        """Get a masking ROI table from the image.
 
-    @overload
-    def get_table(
-        self, name: str, check_type: Literal["masking_roi_table"]
-    ) -> MaskingRoiTable: ...
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, MaskingRoiTable):
+            raise NgioValueError(
+                f"Table {name} is not a masking ROI table. Got {type(table)}"
+            )
+        return table
 
-    @overload
-    def get_table(
-        self, name: str, check_type: Literal["feature_table"]
-    ) -> FeatureTable: ...
+    def get_feature_table(self, name: str) -> FeatureTable:
+        """Get a feature table from the image.
 
-    @overload
-    def get_table(
-        self, name: str, check_type: Literal["generic_roi_table"]
-    ) -> GenericRoiTable: ...
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, FeatureTable):
+            raise NgioValueError(
+                f"Table {name} is not a feature table. Got {type(table)}"
+            )
+        return table
+
+    def get_generic_roi_table(self, name: str) -> GenericRoiTable:
+        """Get a generic ROI table from the image.
+
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, GenericRoiTable):
+            raise NgioValueError(
+                f"Table {name} is not a generic ROI table. Got {type(table)}"
+            )
+        return table
+
+    def get_condition_table(self, name: str) -> ConditionTable:
+        """Get a condition table from the image.
+
+        Args:
+            name (str): The name of the table.
+        """
+        table = self.tables_container.get(name=name, strict=True)
+        if not isinstance(table, ConditionTable):
+            raise NgioValueError(
+                f"Table {name} is not a condition table. Got {type(table)}"
+            )
+        return table
 
     def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
         """Get a table from the image.
 
         Args:
             name (str): The name of the table.
-            check_type (TypedTable | None): The type of the table. If None, the
-                type is not checked. If a type is provided, the table must be of that
-                type.
+            check_type (TypedTable | None): Deprecated. Please use
+                'get_table_as' instead, or one of the type specific
+                get_*table() methods.
+
+        """
+        if check_type is not None:
+            warnings.warn(
+                "The 'check_type' argument is deprecated, and will be removed in "
+                "ngio=0.3. Use 'get_table_as' instead or one of the "
+                "type specific get_*table() methods.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return self.tables_container.get(name=name, strict=False)
+
+    def get_table_as(
+        self,
+        name: str,
+        table_cls: type[TableType],
+        backend: TableBackend | None = None,
+    ) -> TableType:
+        """Get a table from the image as a specific type.
+
+        Args:
+            name (str): The name of the table.
+            table_cls (type[TableType]): The type of the table.
+            backend (TableBackend | None): The backend to use. If None,
+                the default backend is used.
         """
-        if check_type is None:
-            table = self.tables_container.get(name, strict=False)
-            return table
-
-        table = self.tables_container.get(name, strict=True)
-        match check_type:
-            case "roi_table":
-                if not isinstance(table, RoiTable):
-                    raise NgioValueError(
-                        f"Table '{name}' is not a ROI table. Found type: {table.type()}"
-                    )
-                return table
-            case "masking_roi_table":
-                if not isinstance(table, MaskingRoiTable):
-                    raise NgioValueError(
-                        f"Table '{name}' is not a masking ROI table. "
-                        f"Found type: {table.type()}"
-                    )
-                return table
-
-            case "generic_roi_table":
-                if not isinstance(table, GenericRoiTable):
-                    raise NgioValueError(
-                        f"Table '{name}' is not a generic ROI table. "
-                        f"Found type: {table.type()}"
-                    )
-                return table
-
-            case "feature_table":
-                if not isinstance(table, FeatureTable):
-                    raise NgioValueError(
-                        f"Table '{name}' is not a feature table. "
-                        f"Found type: {table.type()}"
-                    )
-                return table
-            case _:
-                raise NgioValueError(f"Unknown check_type: {check_type}")
+        return self.tables_container.get_as(
+            name=name,
+            table_cls=table_cls,
+            backend=backend,
+        )
 
     def build_image_roi_table(self, name: str = "image") -> RoiTable:
         """Compute the ROI table for an image."""
@@ -436,7 +501,7 @@ class OmeZarrContainer:
         self,
         name: str,
         table: Table,
-        backend: str | None = None,
+        backend: TableBackend = "anndata",
         overwrite: bool = False,
     ) -> None:
         """Add a table to the image."""
@@ -446,7 +511,10 @@ class OmeZarrContainer:
 
     def list_labels(self) -> list[str]:
         """List all labels in the image."""
-        return self.labels_container.list()
+        label_container = self._get_labels_container()
+        if label_container is None:
+            return []
+        return label_container.list()
 
     def get_label(
         self,
@@ -499,9 +567,7 @@ class OmeZarrContainer:
         if masking_table_name is None:
             masking_table = masking_label.build_masking_roi_table()
         else:
-            masking_table = self.get_table(
-                masking_table_name, check_type="masking_roi_table"
-            )
+            masking_table = self.get_masking_roi_table(name=masking_table_name)
 
         return MaskedLabel(
             group_handler=label._group_handler,
@@ -566,7 +632,7 @@ def open_ome_zarr_container(
     handler = ZarrGroupHandler(store=store, cache=cache, mode=mode)
     return OmeZarrContainer(
         group_handler=handler,
-        validate_arrays=validate_arrays,
+        validate_paths=validate_arrays,
     )
 
 

ngio/ome_zarr_meta/_meta_handlers.py

@@ -187,10 +187,6 @@ class GenericMetaHandler(
 
         raise NgioValueError(f"Could not load metadata: {meta_or_error}")
 
-    def safe_load_meta(self) -> _image_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."""
         _meta = self._meta_exporter(metadata=meta)
@@ -217,6 +213,10 @@ class ImageMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioImageMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 class LabelMetaHandler(
     GenericMetaHandler[NgioLabelMeta, LabelMetaImporter, LabelMetaExporter]
@@ -230,6 +230,10 @@ class LabelMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioLabelMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 ###########################################################################
 #
@@ -267,10 +271,6 @@ class GenericHCSMetaHandler(Generic[_hcs_meta, _hcs_meta_importer, _hcs_meta_exp
 
         raise NgioValueError(f"Could not load metadata: {meta_or_error}")
 
-    def safe_load_meta(self) -> _hcs_meta | ConverterError:
-        """Load the metadata from the store."""
-        return self._load_meta(return_error=True)
-
     def _write_meta(self, meta) -> None:
         _meta = self._meta_exporter(metadata=meta)
         self._group_handler.write_attrs(_meta)
@@ -295,6 +295,10 @@ class WellMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioWellMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 class PlateMetaHandler(
     GenericHCSMetaHandler[NgioPlateMeta, PlateMetaImporter, PlateMetaExporter]
@@ -308,6 +312,10 @@ class PlateMetaHandler(
             return meta
         raise NgioValueError(f"Could not load metadata: {meta}")
 
+    def safe_load_meta(self) -> NgioPlateMeta | ConverterError:
+        """Load the metadata from the store."""
+        return self._load_meta(return_error=True)
+
 
 ###########################################################################
 #

ngio/ome_zarr_meta/ngio_specs/_channels.py

@@ -329,33 +329,35 @@ class ChannelsMeta(BaseModel):
     @classmethod
     def default_init(
         cls,
-        labels: Collection[str] | int,
-        wavelength_id: Collection[str] | None = None,
-        colors: Collection[str | NgioColors] | None = None,
-        start: Collection[int | float] | int | float | None = None,
-        end: Collection[int | float] | int | float | None = None,
-        active: Collection[bool] | None = None,
+        labels: Collection[str | None] | int,
+        wavelength_id: Collection[str | None] | None = None,
+        colors: Collection[str | NgioColors | None] | None = None,
+        start: Collection[int | float | None] | int | float | None = None,
+        end: Collection[int | float | None] | int | float | None = None,
+        active: Collection[bool | None] | None = None,
         data_type: Any = np.uint16,
         **omero_kwargs: dict,
     ) -> "ChannelsMeta":
         """Create a ChannelsMeta object with the default unit.
 
         Args:
-            labels(Collection[str] | int): The list of channels names in the image.
-                If an integer is provided, the channels will be named "channel_i".
-            wavelength_id(Collection[str] | None): The wavelength ID of the channel.
-                If None, the wavelength ID will be the same as the channel name.
-            colors(Collection[str, NgioColors] | None): The list of colors for the
-                channels. If None, the colors will be random.
-            start(Collection[int | float] | int | float | None): The start value of the
-                channel. If None, the start value will be the minimum value of the
-                data type.
-            end(Collection[int | float] | int | float | None): The end value of the
-                channel. If None, the end value will be the maximum value of the
-                data type.
+            labels(Collection[str | None] | int): The list of channels names
+                in the image. If an integer is provided, the channels will be
+                named "channel_i".
+            wavelength_id(Collection[str | None] | None): The wavelength ID of the
+                channel. If None, the wavelength ID will be the same as the
+                channel name.
+            colors(Collection[str | NgioColors | None] | None): The list of
+                colors for the channels. If None, the colors will be random.
+            start(Collection[int | float | None] | int | float | None): The start
+                value of the channel. If None, the start value will be the
+                minimum value of the data type.
+            end(Collection[int | float | None] | int | float | None): The end
+                value of the channel. If None, the end value will be the
+                maximum value of the data type.
             data_type(Any): The data type of the channel. Will be used to set the
                 min and max values of the channel.
-            active (Collection[bool] | None):active(bool): Whether the channel should
+            active (Collection[bool | None] | None): Whether the channel should
                 be shown by default.
             omero_kwargs(dict): Extra fields to store in the omero attributes.
         """
@@ -366,25 +368,35 @@ class ChannelsMeta(BaseModel):
         labels = _check_unique(labels)
 
         _wavelength_id: Collection[str | None] = [None] * len(labels)
-        if isinstance(wavelength_id, Collection):
+        if wavelength_id is None:
+            _wavelength_id: Collection[str | None] = [None] * len(labels)
+        else:
             _wavelength_id = _check_elements(wavelength_id, str)
             _wavelength_id = _check_unique(wavelength_id)
 
-        _colors: Collection[str | NgioColors | None] = [None] * len(labels)
-        if isinstance(colors, Collection):
+        if colors is None:
+            _colors = [NgioColors.semi_random_pick(label) for label in labels]
+        else:
             _colors = _check_elements(colors, str | NgioColors)
 
-        _start: Collection[int | float | None] = [None] * len(labels)
-        if isinstance(start, Collection):
+        if start is None:
+            _start = [None] * len(labels)
+        elif isinstance(start, int | float):
+            _start = [start] * len(labels)
+        else:
             _start = _check_elements(start, (int, float))
 
-        _end: Collection[int | float | None] = [None] * len(labels)
-        if isinstance(end, Collection):
+        if end is None:
+            _end = [None] * len(labels)
+        elif isinstance(end, int | float):
+            _end = [end] * len(labels)
+        else:
             _end = _check_elements(end, (int, float))
 
-        _active: Collection[bool] = [True] * len(labels)
-        if isinstance(active, Collection):
-            _active = _check_elements(active, bool)
+        if active is None:
+            _active = [True] * len(labels)
+        else:
+            _active = _check_elements(active, (bool,))
 
         all_lengths = [
             len(labels),