ngio 0.3.0a1__py3-none-any.whl → 0.3.2__py3-none-any.whl

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),

ngio/tables/__init__.py

@@ -1,11 +1,6 @@
 """Ngio Tables implementations."""
 
-from ngio.tables.backends import (
-    ImplementedTableBackends,
-    TableBackend,
-    TableBackendProtocol,
-)
-from ngio.tables.tables_container import (
+from ngio.tables._tables_container import (
     ConditionTable,
     FeatureTable,
     GenericRoiTable,
@@ -19,10 +14,17 @@ from ngio.tables.tables_container import (
     open_table_as,
     open_tables_container,
 )
+from ngio.tables.backends import (
+    DefaultTableBackend,
+    ImplementedTableBackends,
+    TableBackend,
+    TableBackendProtocol,
+)
 from ngio.tables.v1._generic_table import GenericTable
 
 __all__ = [
     "ConditionTable",
+    "DefaultTableBackend",
     "FeatureTable",
     "GenericRoiTable",
     "GenericTable",

ngio/tables/{abstract_table.py → _abstract_table.py}

@@ -10,6 +10,7 @@ from anndata import AnnData
 
 from ngio.tables.backends import (
     BackendMeta,
+    DefaultTableBackend,
     ImplementedTableBackends,
     TableBackend,
     TableBackendProtocol,
@@ -203,7 +204,7 @@ class AbstractBaseTable(ABC):
     def set_backend(
         self,
         handler: ZarrGroupHandler | None = None,
-        backend: TableBackend = "anndata",
+        backend: TableBackend = DefaultTableBackend,
     ) -> None:
         """Set the backend of the table."""
         if handler is None:

ngio/tables/{tables_container.py → _tables_container.py}

@@ -8,6 +8,7 @@ import polars as pl
 
 from ngio.tables.backends import (
     BackendMeta,
+    DefaultTableBackend,
     TableBackend,
     TabularData,
 )
@@ -90,7 +91,7 @@ class Table(Protocol):
     def set_backend(
         self,
         handler: ZarrGroupHandler | None = None,
-        backend: TableBackend = "anndata",
+        backend: TableBackend = DefaultTableBackend,
     ) -> None:
         """Set the backend store and path for the table.
 
@@ -126,13 +127,18 @@ class Table(Protocol):
 
 
 TypedTable = Literal[
+    "generic_table",
     "roi_table",
     "masking_roi_table",
     "feature_table",
-    "generic_roi_table",
     "condition_table",
 ]
 
+TypedRoiTable = Literal[
+    "roi_table",
+    "masking_roi_table",
+]
+
 TableType = TypeVar("TableType", bound=Table)
 
 
@@ -192,19 +198,34 @@ class ImplementedTables:
         table = table_cls.from_handler(handler=handler, backend=backend)
         return table
 
-    def add_implementation(self, handler: type[Table], overwrite: bool = False):
+    def _add_implementation(
+        self, handler: type[Table], name: str, overwrite: bool = False
+    ) -> None:
+        """Register a new table handler."""
+        if name in self._implemented_tables and not overwrite:
+            raise NgioValueError(
+                f"Table handler for {name} already implemented. "
+                "Use overwrite=True to replace it."
+            )
+        self._implemented_tables[name] = handler
+
+    def add_implementation(
+        self,
+        handler: type[Table],
+        overwrite: bool = False,
+        aliases: list[str] | None = None,
+    ) -> None:
         """Register a new table handler."""
         meta = TableMeta(
             type=handler.table_type(),
             table_version=handler.version(),
         )
 
-        if meta.unique_name() in self._implemented_tables and not overwrite:
-            raise NgioValueError(
-                f"Table handler for {meta.unique_name()} already implemented. "
-                "Use overwrite=True to replace it."
-            )
-        self._implemented_tables[meta.unique_name()] = handler
+        self._add_implementation(handler, meta.unique_name(), overwrite)
+
+        if aliases is not None:
+            for alias in aliases:
+                self._add_implementation(handler, alias, overwrite)
 
 
 class TablesContainer:
@@ -240,14 +261,7 @@ class TablesContainer:
         handler = self._group_handler.derive_handler(path=name)
         return handler
 
-    def list_roi_tables(self) -> list[str]:
-        """List all ROI tables in the group."""
-        _tables = []
-        for _type in ["roi_table", "masking_roi_table"]:
-            _tables.extend(self.list(_type))
-        return _tables
-
-    def list(self, filter_types: str | None = None) -> list[str]:
+    def list(self, filter_types: TypedTable | str | None = None) -> list[str]:
         """List all labels in the group."""
         tables = self._get_tables_list()
         if filter_types is None:
@@ -301,7 +315,7 @@ class TablesContainer:
         self,
         name: str,
         table: Table,
-        backend: TableBackend = "anndata",
+        backend: TableBackend = DefaultTableBackend,
         overwrite: bool = False,
     ) -> None:
         """Add a table to the group."""
@@ -393,7 +407,7 @@ def open_table_as(
 def write_table(
     store: StoreOrGroup,
     table: Table,
-    backend: TableBackend = "anndata",
+    backend: TableBackend = DefaultTableBackend,
     cache: bool = False,
     mode: AccessModeLiteral = "a",
     parallel_safe: bool = False,

ngio/tables/backends/__init__.py

@@ -6,6 +6,7 @@ from ngio.tables.backends._csv import CsvTableBackend
 from ngio.tables.backends._json import JsonTableBackend
 from ngio.tables.backends._parquet import ParquetTableBackend
 from ngio.tables.backends._table_backends import (
+    DefaultTableBackend,
     ImplementedTableBackends,
     TableBackend,
     TableBackendProtocol,
@@ -32,6 +33,7 @@ __all__ = [
     "AnnDataBackend",
     "BackendMeta",
     "CsvTableBackend",
+    "DefaultTableBackend",
     "ImplementedTableBackends",
     "JsonTableBackend",
     "ParquetTableBackend",

ngio/tables/backends/_abstract_backend.py

@@ -19,7 +19,7 @@ from ngio.utils import NgioValueError, ZarrGroupHandler
 class BackendMeta(BaseModel):
     """Metadata for the backend."""
 
-    backend: str = "anndata"
+    backend: str = "anndata_v1"
     index_key: str | None = None
     index_type: Literal["int", "str"] | None = None
 

ngio/tables/backends/_table_backends.py

@@ -180,24 +180,47 @@ class ImplementedTableBackends:
         )
         return backend
 
-    def add_backend(
+    def _add_backend(
         self,
-        table_beckend: type[TableBackendProtocol],
+        table_backend: type[TableBackendProtocol],
+        name: str,
         overwrite: bool = False,
-    ):
+    ) -> None:
         """Register a new handler."""
-        backend_name = table_beckend.backend_name()
-        if backend_name in self._implemented_backends and not overwrite:
+        if name in self._implemented_backends and not overwrite:
             raise NgioValueError(
-                f"Table backend {backend_name} already implemented. "
+                f"Table backend {name} already implemented. "
                 "Use the `overwrite=True` parameter to overwrite it."
             )
-        self._implemented_backends[backend_name] = table_beckend
-
+        self._implemented_backends[name] = table_backend
 
-ImplementedTableBackends().add_backend(AnnDataBackend)
-ImplementedTableBackends().add_backend(JsonTableBackend)
-ImplementedTableBackends().add_backend(CsvTableBackend)
-ImplementedTableBackends().add_backend(ParquetTableBackend)
+    def add_backend(
+        self,
+        table_backend: type[TableBackendProtocol],
+        overwrite: bool = False,
+        aliases: list[str] | None = None,
+    ) -> None:
+        """Register a new handler."""
+        self._add_backend(
+            table_backend=table_backend,
+            name=table_backend.backend_name(),
+            overwrite=overwrite,
+        )
+        if aliases is not None:
+            for alias in aliases:
+                self._add_backend(
+                    table_backend=table_backend, name=alias, overwrite=overwrite
+                )
+
+
+ImplementedTableBackends().add_backend(AnnDataBackend, aliases=["anndata_v1"])
+ImplementedTableBackends().add_backend(
+    JsonTableBackend, aliases=["experimental_json_v1"]
+)
+ImplementedTableBackends().add_backend(CsvTableBackend, aliases=["experimental_csv_v1"])
+ImplementedTableBackends().add_backend(
+    ParquetTableBackend, aliases=["experimental_parquet_v1"]
+)
 
 TableBackend = Literal["anndata", "json", "csv", "parquet"] | str | TableBackendProtocol
+DefaultTableBackend = "anndata_v1"

ngio/tables/v1/_condition_table.py

@@ -1,6 +1,6 @@
 """Implementation of a generic table class."""
 
-from ngio.tables.abstract_table import AbstractBaseTable
+from ngio.tables._abstract_table import AbstractBaseTable
 from ngio.tables.backends import (
     BackendMeta,
     TableBackend,

ngio/tables/v1/_feature_table.py

@@ -8,7 +8,7 @@ from typing import Literal
 
 from pydantic import BaseModel, Field
 
-from ngio.tables.abstract_table import AbstractBaseTable
+from ngio.tables._abstract_table import AbstractBaseTable
 from ngio.tables.backends import BackendMeta, TableBackend, TabularData
 from ngio.utils import NgioValueError
 from ngio.utils._zarr_utils import ZarrGroupHandler
@@ -26,7 +26,7 @@ class FeatureTableMeta(BackendMeta):
     table_version: Literal["1"] = "1"
     type: Literal["feature_table"] = "feature_table"
     region: RegionMeta | None = None
-    instance_key: str = "label" # Legacy field, kept for compatibility
+    instance_key: str = "label"  # Legacy field, kept for compatibility
     # Backend metadata
     index_key: str | None = "label"
     index_type: Literal["int", "str"] | None = "int"

ngio/tables/v1/_generic_table.py

@@ -1,6 +1,6 @@
 """Implementation of a generic table class."""
 
-from ngio.tables.abstract_table import AbstractBaseTable
+from ngio.tables._abstract_table import AbstractBaseTable
 from ngio.tables.backends import BackendMeta, TableBackend
 from ngio.utils import ZarrGroupHandler
 

ngio/tables/v1/_roi_table.py

@@ -13,7 +13,7 @@ import pandas as pd
 from pydantic import BaseModel
 
 from ngio.common import Roi
-from ngio.tables.abstract_table import (
+from ngio.tables._abstract_table import (
     AbstractBaseTable,
     TabularData,
 )
@@ -47,11 +47,20 @@ REQUIRED_COLUMNS = [
 ORIGIN_COLUMNS = [
     "x_micrometer_original",
     "y_micrometer_original",
+    "z_micrometer_original",
 ]
 
 TRANSLATION_COLUMNS = ["translation_x", "translation_y", "translation_z"]
 
-PLATE_COLUMNS = ["plate_name", "row", "column", "path", "acquisition"]
+PLATE_COLUMNS = [
+    "plate_name",
+    "row",
+    "column",
+    "path_in_well",
+    "path_in_plate",
+    "acquisition_id",
+    "acquisition_name",
+]
 
 INDEX_COLUMNS = [
     "FieldIndex",
@@ -390,7 +399,8 @@ class MaskingRoiTableV1(GenericRoiTableV1):
             meta = MaskingRoiTableV1Meta()
 
         if reference_label is not None:
-            meta.region = RegionMeta(path=reference_label)
+            path = f"../labels/{reference_label}"
+            meta.region = RegionMeta(path=path)
 
         if meta.index_key is None:
             meta.index_key = "label"

ngio/utils/_fractal_fsspec_store.py

@@ -37,6 +37,6 @@ def fractal_fsspec_store(
         raise NgioValueError(
             f"Store {url} can not be read. Possible problems are: \n"
             "- The url does not exist. \n"
-            f"- The url is not a valid .zarr. \n"
+            "- The url is not a valid .zarr. \n"
         )
     return store

{ngio-0.3.0a1.dist-info → ngio-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.3.0a1
+Version: 0.3.2
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/fractal-analytics-platform/ngio
 Project-URL: repository, https://github.com/fractal-analytics-platform/ngio
@@ -63,7 +63,7 @@ Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: scikit-image; extra == 'test'
 Description-Content-Type: text/markdown
 
-# NGIO - Next Generation file format IO
+# Ngio - Next Generation file format IO
 
 [![License](https://img.shields.io/pypi/l/ngio.svg?color=green)](https://github.com/lorenzocerrone/ngio/raw/main/LICENSE)
 [![PyPI](https://img.shields.io/pypi/v/ngio.svg?color=green)](https://pypi.org/project/ngio)
@@ -71,36 +71,69 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/fractal-analytics-platform/ngio/actions/workflows/ci.yml/badge.svg)](https://github.com/fractal-analytics-platform/ngio/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/fractal-analytics-platform/ngio/graph/badge.svg?token=FkmF26FZki)](https://codecov.io/gh/fractal-analytics-platform/ngio)
 
-NGIO is a Python library to streamline OME-Zarr image analysis workflows.
-
-**Main Goals:**
-
-- Abstract object base API for handling OME-Zarr files
-- Powerful iterators for processing data using common access patterns
-- Tight integration with [Fractal's Table Fractal](https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/)
-- Validation of OME-Zarr files
-
-To get started, check out the [Getting Started](https://fractal-analytics-platform.github.io/ngio/getting-started/) guide. Or checkout our [Documentation](https://fractal-analytics-platform.github.io/ngio/)
-
-## 🚧 Ngio is Under active Development 🚧
-
-### Roadmap
-
-| Feature | Status | ETA | Description |
-|---------|--------|-----|-------------|
-| Metadata Handling | ✅ | | Read, Write, Validate OME-Zarr Metadata (0.4 supported, 0.5 ready) |
-| OME-Zarr Validation | ✅ | | Validate OME-Zarr files for compliance with the OME-Zarr Specification + Compliance between Metadata and Data |
-| Base Image Handling | ✅ | | Load data from OME-Zarr files, retrieve basic metadata, and write data |
-| ROI Handling | ✅ | | Common ROI models |
-| Label Handling | ✅ | Mid-September | Based on Image Handling |
-| Table Validation | ✅ | Mid-September | Validate Table fractal V1 + Compliance between Metadata and Data |
-| Table Handling | ✅ | Mid-September | Read, Write ROI, Features, and Masked Tables |
-| Basic Iterators | Ongoing | End-September | Read and Write Iterators for common access patterns |
-| Base Documentation | ✅ | End-September | API Documentation and Examples |
-| Beta Ready Testing | ✅ | End-September | Beta Testing; Library is ready for testing, but the API is not stable |
-| Streaming from Fractal | Ongoing | December | Ngio can stream OME-Zarr from fractal |
-| Mask Iterators | Ongoing | Early 2025 | Iterators over Masked Tables |
-| Advanced Iterators | Not started | mid-2025 | Iterators for advanced access patterns |
-| Parallel Iterators | Not started | mid-2025 | Concurrent Iterators for parallel read and write |
-| Full Documentation | Not started | 2025 | Complete Documentation |
-| Release 1.0 (Commitment to API) | Not started | 2025 | API is stable; breaking changes will be avoided |
+ngio is a Python library designed to simplify bioimage analysis workflows, offering an intuitive interface for working with OME-Zarr files.
+
+## What is Ngio?
+
+Ngio is built for the [OME-Zarr](https://ngff.openmicroscopy.org/) file format, a modern, cloud-optimized format for biological imaging data. OME-Zarr stores large, multi-dimensional microscopy images and metadata in an efficient and scalable way.
+
+Ngio's mission is to streamline working with OME-Zarr files by providing a simple, object-based API for opening, exploring, and manipulating OME-Zarr images and high-content screening (HCS) plates. It also offers comprehensive support for labels, tables and regions of interest (ROIs), making it easy to extract and analyze specific regions in your data.
+
+## Key Features
+
+### 📊 Simple Object-Based API
+
+- Easily open, explore, and manipulate OME-Zarr images and HCS plates
+- Create and derive new images and labels with minimal boilerplate code
+
+### 🔍 Rich Tables and Regions of Interest (ROI) Support
+
+- Extract and analyze specific regions of interest
+- Tight integration with [Tabular Data](https://fractal-analytics-platform.github.io/ngio/stable/table_specs/overview/)
+
+### 🔄 Scalable Data Processing (Coming Soon)
+
+- Powerful iterators for processing data at scale
+- Efficient memory management for large datasets
+
+## Installation
+
+You can install ngio via pip:
+
+```bash
+pip install ngio
+```
+
+To get started check out the [Quickstart Guide](https://fractal-analytics-platform.github.io/ngio/stable/getting_started/0_quickstart/).
+
+## Supported OME-Zarr versions
+
+Currently, ngio only supports OME-Zarr v0.4. Support for version 0.5 and higher is planned for future releases.
+
+## Development Status
+
+!!! warning
+    Ngio is under active development and is not yet stable. The API is subject to change, and bugs and breaking changes are expected.
+    We follow [Semantic Versioning](https://semver.org/). Which means for 0.x releases potentially breaking changes can be introduced in minor releases.
+
+### Available Features
+
+- ✅ OME-Zarr metadata handling and validation
+- ✅ Image and label access across pyramid levels
+- ✅ ROI and table support
+- ✅ Streaming from remote sources
+- ✅ Documentation and examples
+
+### Upcoming Features
+
+- Advanced image processing iterators
+- Parallel processing capabilities
+- Support for OME-Zarr v0.5 and Zarr v3
+
+## Contributors
+
+Ngio is developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html), University of Zurich, by [@lorenzocerrone](https://github.com/lorenzocerrone) and [@jluethi](https://github.com/jluethi).
+
+## License
+
+Ngio is released under the BSD-3-Clause License. See [LICENSE](https://github.com/fractal-analytics-platform/ngio/blob/main/LICENSE) for details.