remove deprecation warning and promote iterators

docs/api/iterators.md

@@ -4,23 +4,18 @@ description: API reference for the ngio processing iterators.
 
 # Iterators API reference
 
-!!! warning "Experimental API"
-
-    These classes live in `ngio.experimental.iterators` and may change or be removed in a
-    future release without notice.
-
 ## ImageProcessingIterator
 
-::: ngio.experimental.iterators.ImageProcessingIterator
+::: ngio.iterators.ImageProcessingIterator
 
 ## SegmentationIterator
 
-::: ngio.experimental.iterators.SegmentationIterator
+::: ngio.iterators.SegmentationIterator
 
 ## MaskedSegmentationIterator
 
-::: ngio.experimental.iterators.MaskedSegmentationIterator
+::: ngio.iterators.MaskedSegmentationIterator
 
 ## FeatureExtractorIterator
 
-::: ngio.experimental.iterators.FeatureExtractorIterator
+::: ngio.iterators.FeatureExtractorIterator

docs/api/ngio/iterators.md

@@ -1,3 +1,3 @@
-# ngio.experimental.iterators API reference
+# ngio.iterators API reference
 
-::: ngio.experimental.iterators
+::: ngio.iterators

docs/getting_started/6_iterators.md

@@ -8,13 +8,6 @@ description: The four ngio iterators for building scalable image-processing pipe
 
 When building image processing pipelines it is often useful to iterate over specific regions of the image, for example to process the image in smaller tiles or to process only specific regions of interest (ROIs). Iterators also let you set broadcasting rules for the iteration, for example to iterate over all z-planes or over all timepoints.
 
-!!! warning "Experimental API"
-
-    The iterators live in `ngio.experimental.iterators`, outside the stability guarantee
-    that covers the rest of ngio: they may change or be removed in a future release
-    without notice. Everything on this page works today, but pin your ngio version if you
-    depend on it.
-
 <!-- Figure 05 — how an iterator walks -->
 <div class="ngio-diagram">
 <svg viewBox="0 0 640 232" style="display:block;width:100%;height:auto" role="img" aria-labelledby="f5t f5d">
@@ -100,8 +93,8 @@ When building image processing pipelines it is often useful to iterate over spec
         </svg>
 </div>
 
-ngio provides four basic `Iterator` classes, all imported from
-`ngio.experimental.iterators`:
+ngio provides four basic `Iterator` classes, all imported from `ngio.iterators` (or from
+the top-level `ngio` namespace):
 
 <!-- Figure 06 — which iterator do I want -->
 <div class="ngio-diagram">

docs/llms.txt

@@ -48,7 +48,7 @@ guides and tutorials are executed when the site is built, so the outputs shown a
 - [Images](https://biovisioncenter.github.io/ngio/stable/api/images/): Image and Label objects and their accessors.
 - [HCS](https://biovisioncenter.github.io/ngio/stable/api/hcs/): open_ome_zarr_plate, OmeZarrPlate, open_ome_zarr_well, OmeZarrWell, create_empty_plate, create_empty_well.
 - [Tables](https://biovisioncenter.github.io/ngio/stable/api/tables/): Table classes, the tables container and backends.
-- [Iterators](https://biovisioncenter.github.io/ngio/stable/api/iterators/): ImageProcessingIterator, SegmentationIterator, MaskedSegmentationIterator, FeatureExtractorIterator — experimental, from ngio.experimental.iterators.
+- [Iterators](https://biovisioncenter.github.io/ngio/stable/api/iterators/): ImageProcessingIterator, SegmentationIterator, MaskedSegmentationIterator, FeatureExtractorIterator — from ngio.iterators.
 - [ngio top-level API](https://biovisioncenter.github.io/ngio/stable/api/ngio/ngio/): Roi, PixelSize, Dimensions, NgioConfig and other core types.
 
 ## Optional

docs/snippets/getting_started/iterators.py

@@ -11,7 +11,7 @@
 from pathlib import Path
 
 from ngio import open_ome_zarr_container
-from ngio.experimental.iterators import ImageProcessingIterator
+from ngio.iterators import ImageProcessingIterator
 from ngio.utils import download_ome_zarr_dataset
 
 download_dir = Path("./data").absolute()

docs/snippets/tutorials/feature_extraction.py

@@ -82,7 +82,7 @@ def extract_features(image: np.ndarray, label: np.ndarray) -> pd.DataFrame:
 # --8<-- [end:setup_transform]
 
 # --8<-- [start:extract]
-from ngio.experimental.iterators import FeatureExtractorIterator
+from ngio.iterators import FeatureExtractorIterator
 from ngio.tables import FeatureTable
 
 iterator = FeatureExtractorIterator(

docs/snippets/tutorials/image_processing.py

@@ -121,7 +121,7 @@ def dask_gaussian_blur(image: da.Array, sigma: float) -> da.Array:
 # --8<-- [end:dask_blur]
 
 # --8<-- [start:iterators]
-from ngio.experimental.iterators import ImageProcessingIterator
+from ngio.iterators import ImageProcessingIterator
 
 iterator = ImageProcessingIterator(
     input_image=image,

docs/snippets/tutorials/image_segmentation.py

@@ -55,7 +55,7 @@ def otsu_threshold_segmentation(image: np.ndarray, max_label: int) -> np.ndarray
 # --8<-- [end:open_container]
 
 # --8<-- [start:segment]
-from ngio.experimental.iterators import SegmentationIterator
+from ngio.iterators import SegmentationIterator
 
 # Take the image to read from, and the FOV table naming the regions to walk
 image = ome_zarr.get_image()
@@ -140,7 +140,7 @@ def otsu_threshold_segmentation(image: np.ndarray, max_label: int) -> np.ndarray
 # --8<-- [end:plot_mask]
 
 # --8<-- [start:masked_segment]
-from ngio.experimental.iterators import MaskedSegmentationIterator
+from ngio.iterators import MaskedSegmentationIterator
 
 # Take a masked image, which carries its masking ROI table with it
 image = ome_zarr.get_masked_image(masking_label_name="mask")

mkdocs.yml

@@ -217,7 +217,7 @@ nav:
       - "ngio": api/ngio/ngio.md
       - "ngio.common": api/ngio/common.md
       - "ngio.io_pipes": api/ngio/io_pipes.md
-      - "ngio.experimental.iterators": api/ngio/iterators.md
+      - "ngio.iterators": api/ngio/iterators.md
       - "ngio.images": api/ngio/images.md
       - "ngio.tables": api/ngio/tables.md
       - "ngio.hcs": api/ngio/hcs.md

src/ngio/__init__.py

@@ -31,6 +31,12 @@
     open_label,
     open_ome_zarr_container,
 )
+from ngio.iterators import (
+    FeatureExtractorIterator,
+    ImageProcessingIterator,
+    MaskedSegmentationIterator,
+    SegmentationIterator,
+)
 from ngio.ome_zarr_meta.ngio_specs import (
     AxesSetup,
     DefaultNgffVersion,
@@ -45,9 +51,12 @@
     "ChannelSelectionModel",
     "DefaultNgffVersion",
     "Dimensions",
+    "FeatureExtractorIterator",
     "Image",
     "ImageInWellPath",
+    "ImageProcessingIterator",
     "Label",
+    "MaskedSegmentationIterator",
     "NgffVersions",
     "NgioConfig",
     "NgioSupportedStore",
@@ -58,6 +67,7 @@
     "RetryConfig",
     "Roi",
     "RoiSlice",
+    "SegmentationIterator",
     "StoreOrGroup",
     "create_empty_ome_zarr",
     "create_empty_plate",

src/ngio/experimental/__init__.py

@@ -1,5 +1,5 @@
-"""This module provides experimental features.
+"""Deprecated namespace for features that have since graduated.
 
-Use with caution as these features may change or be removed in future releases
-without notice.
+`ngio.experimental.iterators` is a shim for `ngio.iterators` and will be
+removed in ngio 1.1.
 """

src/ngio/experimental/iterators/__init__.py

@@ -1,15 +1,41 @@
-"""This file is part of NGIO, a library for working with OME-Zarr data."""
+"""Deprecated alias for `ngio.iterators`.
 
-from ngio.experimental.iterators._feature import FeatureExtractorIterator
-from ngio.experimental.iterators._image_processing import ImageProcessingIterator
-from ngio.experimental.iterators._segmentation import (
-    MaskedSegmentationIterator,
-    SegmentationIterator,
-)
+The iterators are no longer experimental. Import them from `ngio.iterators`
+(or from `ngio` directly). This module will be removed in ngio 1.1.
+"""
+
+import warnings
+from typing import TYPE_CHECKING, Any
+
+from ngio.utils import NgioDeprecationWarning
+
+if TYPE_CHECKING:
+    from ngio.iterators import (
+        FeatureExtractorIterator,
+        ImageProcessingIterator,
+        MaskedSegmentationIterator,
+        SegmentationIterator,
+    )
 
 __all__ = [
     "FeatureExtractorIterator",
     "ImageProcessingIterator",
     "MaskedSegmentationIterator",
     "SegmentationIterator",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    """Forward attribute access to `ngio.iterators` with a deprecation warning."""
+    if name not in __all__:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    warnings.warn(
+        f"'ngio.experimental.iterators.{name}' is deprecated and will be removed "
+        f"in ngio=1.1. Please use 'ngio.iterators.{name}' instead.",
+        NgioDeprecationWarning,
+        stacklevel=2,
+    )
+    import ngio.iterators
+
+    return getattr(ngio.iterators, name)

src/ngio/hcs/_plate.py

@@ -2,7 +2,6 @@
 
 import asyncio
 import logging
-import warnings
 from collections.abc import Sequence
 from typing import Literal
 
@@ -42,7 +41,6 @@
 from ngio.utils import (
     AccessModeLiteral,
     NgioCache,
-    NgioDeprecationWarning,
     NgioError,
     NgioValueError,
     StoreOrGroup,
@@ -783,7 +781,6 @@ def derive_plate(
         self,
         store: StoreOrGroup,
         plate_name: str | None = None,
-        version: NgffVersions | None = None,
         ngff_version: NgffVersions | None = None,
         keep_acquisitions: bool = False,
         cache: bool = False,
@@ -794,7 +791,6 @@ def derive_plate(
         Args:
             store (StoreOrGroup): The Zarr store or group that stores the plate.
             plate_name (str | None): The name of the new plate.
-            version (NgffVersion | None): Deprecated. Please use 'ngff_version' instead.
             ngff_version (NgffVersion): The NGFF version to use for the new plate.
             keep_acquisitions (bool): Whether to keep the acquisitions in the new plate.
             cache (bool): Whether to use a cache for the zarr group metadata.
@@ -805,7 +801,6 @@ def derive_plate(
             store=store,
             plate_name=plate_name,
             ngff_version=ngff_version,
-            version=version,
             keep_acquisitions=keep_acquisitions,
             cache=cache,
             overwrite=overwrite,
@@ -911,24 +906,12 @@ def get_condition_table(self, name: str) -> ConditionTable:
             )
         return table
 
-    def get_table(self, name: str, check_type: TypedTable | None = None) -> Table:
+    def get_table(self, name: str) -> Table:
         """Get a table from the image.
 
         Args:
             name (str): The name of the table.
-            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.6. Please use 'get_table_as' instead or one of the "
-                "type specific get_*table() methods.",
-                NgioDeprecationWarning,
-                stacklevel=2,
-            )
         return self.tables_container.get(name=name, strict=False)
 
     def get_table_as(
@@ -1212,7 +1195,6 @@ def create_empty_plate(
     store: StoreOrGroup,
     name: str,
     images: list[ImageInWellPath] | None = None,
-    version: NgffVersions | None = None,
     ngff_version: NgffVersions = DefaultNgffVersion,
     cache: bool = False,
     overwrite: bool = False,
@@ -1224,19 +1206,10 @@ def create_empty_plate(
         name (str): The name of the plate.
         images (list[ImageInWellPath] | None): A list of images to add to the plate.
             If None, no images are added. Defaults to None.
-        version (NgffVersion | None): Deprecated. Please use 'ngff_version' instead.
         ngff_version (NgffVersion): The NGFF version to use for the new plate.
         cache (bool): Whether to use a cache for the zarr group metadata.
         overwrite (bool): Whether to overwrite the existing plate.
     """
-    if version is not None:
-        warnings.warn(
-            "The 'version' argument is deprecated and will be removed in ngio=0.6. "
-            "Please use 'ngff_version' instead.",
-            NgioDeprecationWarning,
-            stacklevel=2,
-        )
-        ngff_version = version
     plate_meta = NgioPlateMeta.default_init(
         name=name,
         ngff_version=ngff_version,
@@ -1268,7 +1241,6 @@ def derive_ome_zarr_plate(
     ome_zarr_plate: OmeZarrPlate,
     store: StoreOrGroup,
     plate_name: str | None = None,
-    version: NgffVersions | None = None,
     ngff_version: NgffVersions | None = None,
     keep_acquisitions: bool = False,
     cache: bool = False,
@@ -1280,21 +1252,11 @@ def derive_ome_zarr_plate(
         ome_zarr_plate (OmeZarrPlate): The existing OME-Zarr plate.
         store (StoreOrGroup): The Zarr store or group that stores the plate.
         plate_name (str | None): The name of the new plate.
-        version (NgffVersion | None): Deprecated. Please use 'ngff_version' instead.
         ngff_version (NgffVersion): The NGFF version to use for the new plate.
         keep_acquisitions (bool): Whether to keep the acquisitions in the new plate.
         cache (bool): Whether to use a cache for the zarr group metadata.
         overwrite (bool): Whether to overwrite the existing plate.
     """
-    if version is not None:
-        warnings.warn(
-            "The 'version' argument is deprecated and will be removed in ngio=0.6. "
-            "Please use 'ngff_version' instead.",
-            NgioDeprecationWarning,
-            stacklevel=2,
-        )
-        ngff_version = version
-
     if ngff_version is None:
         ngff_version = ome_zarr_plate.meta.plate.version or DefaultNgffVersion
 
@@ -1340,7 +1302,6 @@ def open_ome_zarr_well(
 
 def create_empty_well(
     store: StoreOrGroup,
-    version: NgffVersions | None = None,
     ngff_version: NgffVersions = DefaultNgffVersion,
     cache: bool = False,
     overwrite: bool = False,
@@ -1349,19 +1310,10 @@ def create_empty_well(
 
     Args:
         store (StoreOrGroup): The Zarr store or group that stores the well.
-        version (NgffVersion | None): Deprecated. Please use 'ngff_version' instead.
         ngff_version (NgffVersion): The version of the new well.
         cache (bool): Whether to use a cache for the zarr group metadata.
         overwrite (bool): Whether to overwrite the existing well.
     """
-    if version is not None:
-        warnings.warn(
-            "The 'version' argument is deprecated and will be removed in ngio=0.6. "
-            "Please use 'ngff_version' instead.",
-            NgioDeprecationWarning,
-            stacklevel=2,
-        )
-        ngff_version = version
     group_handler = ZarrGroupHandler(
         store=store, cache=True, mode="w" if overwrite else "w-"
     )