ngio 0.2.0a2__tar.gz → 0.2.0a3__tar.gz

{ngio-0.2.0a2 → ngio-0.2.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.2.0a2
+Version: 0.2.0a3
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/lorenzocerrone/ngio
 Project-URL: repository, https://github.com/lorenzocerrone/ngio

ngio-0.2.0a3/docs/api/core.md

@@ -0,0 +1,3 @@
+# ngio
+
+Work in progress! Sorry!

{ngio-0.2.0a2 → ngio-0.2.0a3}/docs/notebooks/basic_usage.ipynb

@@ -10,15 +10,6 @@
     "\n",
     "For this example we will use a small example image that can be downloaded from the following link: [example ome-zarr](https://zenodo.org/records/13305156)\n",
     "\n",
-    "## Setup\n",
-    "\n",
-    "You can download the example image (on Linux and Mac os) by running the following command:\n",
-    "\n",
-    "```bash\n",
-    "bash setup_data.sh\n",
-    "```\n",
-    "from the root of the repository.\n",
-    "\n",
     "## OmeZarr Container\n",
     "\n",
     "The `OmeZarr Container` provides a high-level interface to read, write and manipulate NGFF images.\n",
@@ -95,7 +86,9 @@
     "print(image)\n",
     "\n",
     "# 3. Get image from a specific pixel size using the pixel_size keyword\n",
-    "image = omezarr_container.get_image(pixel_size=PixelSize(x=0.65, y=0.65, z=1))\n",
+    "image = omezarr_container.get_image(\n",
+    "    pixel_size=PixelSize(x=0.65, y=0.65, z=1000), strict=True\n",
+    ")\n",
     "print(image)"
    ]
   },
@@ -253,6 +246,32 @@
     "print(new_omezarr_image)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Create an OmeZarr From a Numpy Array\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "from ngio import create_omezarr_from_array\n",
+    "\n",
+    "x = np.random.randint(0, 255, (16, 128, 128), dtype=np.uint8)\n",
+    "\n",
+    "new_omezarr_image = create_omezarr_from_array(\n",
+    "    store=\"random_ome.zarr\", array=x, xy_pixelsize=0.65, z_spacing=1.0\n",
+    ")\n",
+    "print(new_omezarr_image)\n",
+    "print(new_omezarr_image.get_image())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -284,6 +303,50 @@
     "omezarr"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Streaming an OmeZarr from a Fractal Server\n",
+    "\n",
+    "Example:\n",
+    "\n",
+    "```python\n",
+    "from ngio.utils import fractal_fsspec_store\n",
+    "\n",
+    "store = fractal_fsspec_store(url=\"https://fracral_url...\", fractal_token=\"**your_secret_token**\")\n",
+    "omezarr = open_omezarr_container(store)\n",
+    "omezarr\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ngio import open_omezarr_container\n",
+    "from ngio.utils import fractal_fsspec_store\n",
+    "\n",
+    "store = fractal_fsspec_store(\n",
+    "    url=\"https://fractal.mls.uzh.ch/vizarr/data/data/active/lorcerr/fractal/104_altmeyer_10097/443_experiment3/AP411_U2OS.zarr/A/1/0\",\n",
+    "    fractal_token=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MCIsImF1ZCI6WyJmYXN0YXBpLXVzZXJzOmF1dGgiXSwiZXhwIjoxNzQxMzY1NzY2fQ.wnpJSL6rtkKIoFeW7D31sVpEXeDcD0VrahwbF4CGbNI\",\n",
+    ")\n",
+    "omezarr = open_omezarr_container(store)\n",
+    "print(omezarr)\n",
+    "print(omezarr.get_image(path=\"3\").get_array())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "omezarr.get_image(path=\"3\").get_array()"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

{ngio-0.2.0a2 → ngio-0.2.0a3}/docs/notebooks/image.ipynb

@@ -216,7 +216,7 @@
    "outputs": [],
    "source": [
     "# Create a a new label object and set it to a simple segmentation\n",
-    "new_label = omezarr.derive_label(\"new_label_2\", overwrite=True)\n",
+    "new_label = omezarr.derive_label(\"new_label\", overwrite=True)\n",
     "\n",
     "simple_segmentation = image.get_array(c=0) > 100\n",
     "simple_segmentation = simple_segmentation[0]\n",
@@ -225,7 +225,7 @@
     "# make a subplot with two image show side by side\n",
     "fig, axs = plt.subplots(1, 2, figsize=(10, 5))\n",
     "axs[0].imshow(image.get_array()[0, 0], cmap=\"gray\")\n",
-    "axs[1].imshow(new_label.get_array()[0], cmap=\"gray\")\n",
+    "axs[1].imshow(new_label.get_array()[0])\n",
     "for ax in axs:\n",
     "    ax.axis(\"off\")\n",
     "plt.tight_layout()\n",
@@ -327,13 +327,6 @@
     "feat_table = omezarr.get_table(\"new_feature_table\")\n",
     "feat_table.dataframe"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {

{ngio-0.2.0a2 → ngio-0.2.0a3}/src/ngio/images/image.py

@@ -170,17 +170,20 @@ class ImagesContainer:
                 be shown by default.
             omero_kwargs(dict): Extra fields to store in the omero attributes.
         """
-        ref = self.get()
+        low_res_dataset = self.meta.get_lowest_resolution_dataset()
+        ref_image = self.get(path=low_res_dataset.path)
 
         if percentiles is not None:
             start, end = compute_image_percentile(
-                ref, start_percentile=percentiles[0], end_percentile=percentiles[1]
+                ref_image,
+                start_percentile=percentiles[0],
+                end_percentile=percentiles[1],
             )
         else:
             start, end = None, None
 
         if labels is None:
-            labels = ref.num_channels
+            labels = ref_image.num_channels
 
         channel_meta = ChannelsMeta.default_init(
             labels=labels,
@@ -189,7 +192,7 @@ class ImagesContainer:
             start=start,
             end=end,
             active=active,
-            data_type=ref.dtype,
+            data_type=ref_image.dtype,
             **omero_kwargs,
         )
 
@@ -206,9 +209,10 @@ class ImagesContainer:
         if self.meta._channels_meta is None:
             raise NgioValidationError("The channels meta is not initialized.")
 
-        image = self.get()
+        low_res_dataset = self.meta.get_lowest_resolution_dataset()
+        ref_image = self.get(path=low_res_dataset.path)
         starts, ends = compute_image_percentile(
-            image, start_percentile=start_percentile, end_percentile=end_percentile
+            ref_image, start_percentile=start_percentile, end_percentile=end_percentile
         )
 
         channels = []
@@ -256,13 +260,20 @@ class ImagesContainer:
         self,
         path: str | None = None,
         pixel_size: PixelSize | None = None,
-        highest_resolution: bool = True,
+        strict: bool = False,
     ) -> Image:
-        """Get an image at a specific level."""
-        if path is not None or pixel_size is not None:
-            highest_resolution = False
+        """Get an image at a specific level.
+
+        Args:
+            path (str | None): The path to the image in the omezarr file.
+            pixel_size (PixelSize | None): The pixel size of the image.
+            strict (bool): Only used if the pixel size is provided. If True, the
+                pixel size must match the image pixel size exactly. If False, the
+                closest pixel size level will be returned.
+
+        """
         dataset = self._meta_handler.meta.get_dataset(
-            path=path, pixel_size=pixel_size, highest_resolution=highest_resolution
+            path=path, pixel_size=pixel_size, strict=strict
         )
         return Image(
             group_handler=self._group_handler,

{ngio-0.2.0a2 → ngio-0.2.0a3}/src/ngio/images/label.py

@@ -10,6 +10,7 @@ from ngio.ome_zarr_meta import (
     ImplementedLabelMetaHandlers,
     LabelMetaHandler,
     NgioLabelMeta,
+    PixelSize,
 )
 from ngio.ome_zarr_meta.ngio_specs import SpaceUnits, TimeUnits
 from ngio.utils import (
@@ -86,11 +87,38 @@ class LabelsContainer:
         attrs = self._group_handler.load_attrs()
         return attrs.get("labels", [])
 
-    def get(self, name: str, path: str) -> Label:
+    def _get(self, name: str, path: str) -> Label:
         """Get a label from the group."""
         group_handler = self._group_handler.derive_handler(name)
         return Label(group_handler, path, None)
 
+    def get(
+        self,
+        name: str,
+        path: str | None = None,
+        pixel_size: PixelSize | None = None,
+        strict: bool = False,
+    ) -> Label:
+        """Get a label from the group.
+
+        Args:
+            name (str): The name of the label.
+            path (str | None): The path to the image in the omezarr file.
+            pixel_size (PixelSize | None): The pixel size of the image.
+            strict (bool): Only used if the pixel size is provided. If True, the
+                pixel size must match the image pixel size exactly. If False, the
+                closest pixel size level will be returned.
+
+        """
+        group_handler = self._group_handler.derive_handler(name)
+        label_meta_handler = ImplementedLabelMetaHandlers().find_meta_handler(
+            group_handler
+        )
+        path = label_meta_handler.meta.get_dataset(
+            path=path, pixel_size=pixel_size, strict=strict
+        ).path
+        return Label(group_handler, path, label_meta_handler)
+
     def derive(
         self,
         name: str,

{ngio-0.2.0a2 → ngio-0.2.0a3}/src/ngio/images/omezarr_container.py

@@ -160,13 +160,20 @@ class OmeZarrContainer:
         self,
         path: str | None = None,
         pixel_size: PixelSize | None = None,
-        highest_resolution: bool = True,
+        strict: bool = False,
     ) -> Image:
-        """Get an image at a specific level."""
+        """Get an image at a specific level.
+
+        Args:
+            path (str | None): The path to the image in the omezarr file.
+            pixel_size (PixelSize | None): The pixel size of the image.
+            strict (bool): Only used if the pixel size is provided. If True, the
+                pixel size must match the image pixel size exactly. If False, the
+                closest pixel size level will be returned.
+
+        """
         return self._images_container.get(
-            path=path,
-            pixel_size=pixel_size,
-            highest_resolution=highest_resolution,
+            path=path, pixel_size=pixel_size, strict=strict
         )
 
     def derive_image(
@@ -279,11 +286,28 @@ class OmeZarrContainer:
             return []
         return self._labels_container.list()
 
-    def get_label(self, name: str, path: str) -> Label:
-        """Get a label from the image."""
+    def get_label(
+        self,
+        name: str,
+        path: str | None = None,
+        pixel_size: PixelSize | None = None,
+        strict: bool = False,
+    ) -> Label:
+        """Get a label from the group.
+
+        Args:
+            name (str): The name of the label.
+            path (str | None): The path to the image in the omezarr file.
+            pixel_size (PixelSize | None): The pixel size of the image.
+            strict (bool): Only used if the pixel size is provided. If True, the
+                pixel size must match the image pixel size exactly. If False, the
+                closest pixel size level will be returned.
+        """
         if self._labels_container is None:
             raise NgioValidationError("No labels found in the image.")
-        return self._labels_container.get(name=name, path=path)
+        return self._labels_container.get(
+            name=name, path=path, pixel_size=pixel_size, strict=strict
+        )
 
     def derive_label(
         self,
@@ -334,17 +358,29 @@ def open_image(
     store: StoreOrGroup,
     path: str | None = None,
     pixel_size: PixelSize | None = None,
-    highest_resolution: bool = False,
+    strict: bool = True,
     cache: bool = False,
     mode: AccessModeLiteral = "r+",
 ) -> Image:
-    """Open a single level image from an OME-Zarr image."""
+    """Open a single level image from an OME-Zarr image.
+
+    Args:
+        store (StoreOrGroup): The Zarr store or group to create the image in.
+        path (str | None): The path to the image in the omezarr file.
+        pixel_size (PixelSize | None): The pixel size of the image.
+        strict (bool): Only used if the pixel size is provided. If True, the
+                pixel size must match the image pixel size exactly. If False, the
+                closest pixel size level will be returned.
+        cache (bool): Whether to use a cache for the zarr group metadata.
+        mode (AccessModeLiteral): The
+            access mode for the image. Defaults to "r+".
+    """
     group_handler = ZarrGroupHandler(store, cache, mode)
     images_container = ImagesContainer(group_handler)
     return images_container.get(
         path=path,
         pixel_size=pixel_size,
-        highest_resolution=highest_resolution,
+        strict=strict,
     )
 
 

{ngio-0.2.0a2 → ngio-0.2.0a3}/src/ngio/ome_zarr_meta/ngio_specs/_ngio_image.py

@@ -138,16 +138,16 @@ class AbstractNgioImageMeta:
         path: str | None = None,
         idx: int | None = None,
         pixel_size: PixelSize | None = None,
-        highest_resolution: bool = False,
         strict: bool = False,
     ) -> Dataset:
         """Get a dataset by its path, index or pixel size.
 
+        If all arguments are None, the dataset with the highest resolution is returned.
+
         Args:
             path(str): The path of the dataset.
             idx(int): The index of the dataset.
             pixel_size(PixelSize): The pixel size to search for.
-            highest_resolution(bool): If True, the dataset with the highest resolution
             strict(bool): If True, the pixel size must be exactly the same.
                 If pixel_size is None, strict is ignored.
         """
@@ -158,12 +158,11 @@ class AbstractNgioImageMeta:
                     path is not None,
                     idx is not None,
                     pixel_size is not None,
-                    highest_resolution,
                 ]
             )
-            != 1
+            > 1
         ):
-            raise NgioValueError("get_dataset must receive only one argument.")
+            raise NgioValueError("get_dataset must receive only one argument or None.")
 
         if path is not None:
             return self._get_dataset_by_path(path)
@@ -171,10 +170,8 @@ class AbstractNgioImageMeta:
             return self._get_dataset_by_index(idx)
         elif pixel_size is not None:
             return self._get_dataset_by_pixel_size(pixel_size, strict=strict)
-        elif highest_resolution:
-            return self.get_highest_resolution_dataset()
         else:
-            raise NgioValueError("get_dataset has no valid arguments.")
+            return self.get_highest_resolution_dataset()
 
     @classmethod
     def default_init(
@@ -237,6 +234,20 @@ class AbstractNgioImageMeta:
             strict=False,
         )
 
+    def get_lowest_resolution_dataset(self) -> Dataset:
+        """Get the dataset with the lowest resolution."""
+        return self._get_dataset_by_pixel_size(
+            pixel_size=PixelSize(
+                x=1000.0,
+                y=1000.0,
+                z=1000.0,
+                t=1000.0,
+                space_unit=SpaceUnits.micrometer,
+                time_unit=TimeUnits.s,
+            ),
+            strict=False,
+        )
+
     def get_scaling_factor(self, axis_name: str) -> float:
         """Get the scaling factors of the dataset."""
         scaling_factors = []

{ngio-0.2.0a2 → ngio-0.2.0a3}/src/ngio/utils/__init__.py

@@ -11,6 +11,7 @@ from ngio.utils._errors import (
     NgioValidationError,
     NgioValueError,
 )
+from ngio.utils._fractal_fsspec_store import fractal_fsspec_store
 from ngio.utils._logger import ngio_logger, set_logger_level
 from ngio.utils._zarr_utils import (
     AccessModeLiteral,
@@ -35,6 +36,8 @@ __all__ = [
     "ZarrGroupHandler",
     # Datasets
     "download_ome_zarr_dataset",
+    # Fractal
+    "fractal_fsspec_store",
     "list_ome_zarr_datasets",
     # Logger
     "ngio_logger",

ngio-0.2.0a3/src/ngio/utils/_fractal_fsspec_store.py

@@ -0,0 +1,12 @@
+import fsspec.implementations.http
+
+
+def fractal_fsspec_store(
+    url: str, fractal_token: str, client_kwargs: dict | None = None
+) -> fsspec.mapping.FSMap:
+    """Simple function to get an http fsspec store from a url."""
+    client_kwargs = {} if client_kwargs is None else client_kwargs
+    client_kwargs["headers"] = {"Authorization": f"Bearer {fractal_token}"}
+    fs = fsspec.implementations.http.HTTPFileSystem(client_kwargs=client_kwargs)
+    store = fs.get_mapper(url)
+    return store

{ngio-0.2.0a2 → ngio-0.2.0a3}/tests/unit/images/test_omezarr_container.py

@@ -26,10 +26,13 @@ def test_omezarr_container(tmp_path: Path, array_mode: str):
     assert omezarr.levels_paths == ["0", "1", "2"]
 
     image = omezarr.get_image()
+
     assert image.shape == (10, 20, 30)
     assert image.dtype == "uint8"
     assert image.chunks == (1, 20, 30)
     assert image.pixel_size.x == 0.5
+    assert image.meta.get_highest_resolution_dataset().path == "0"
+    assert image.meta.get_lowest_resolution_dataset().path == "2"
 
     array = image.get_array(
         x=slice(None), axes_order=["c", "z", "y", "x"], mode=array_mode

{ngio-0.2.0a2 → ngio-0.2.0a3}/tests/unit/test_ome_zarr_meta/test_unit_ngio_specs.py

@@ -380,7 +380,7 @@ def test_image_meta():
     assert np.isclose(image_meta.z_scaling_factor, 1.0)
     assert image_meta.get_dataset(path="0").path == "0"
     assert image_meta.get_dataset(path="1").path == "1"
-    assert image_meta.get_dataset(highest_resolution=True).path == "0"
+    assert image_meta.get_dataset().path == "0"
     assert image_meta.get_dataset(pixel_size=datasets[-1].pixel_size).path == "3"
     assert image_meta.get_channel_idx(label="DAPI") == 0
     assert image_meta.get_channel_idx(wavelength_id="DAPI") == 0
@@ -426,7 +426,7 @@ def test_label_meta():
     assert np.isclose(label_meta.z_scaling_factor, 1.0)
     assert label_meta.get_dataset(path="0").path == "0"
     assert label_meta.get_dataset(path="1").path == "1"
-    assert label_meta.get_dataset(highest_resolution=True).path == "0"
+    assert label_meta.get_dataset().path == "0"
     assert label_meta.get_dataset(pixel_size=datasets[-1].pixel_size).path == "3"
 
 

ngio-0.2.0a2/docs/api/core.md

@@ -1,8 +0,0 @@
-# ngio.core
-
-::: ngio.core
-    options:
-        members: no
-
-## NGFFImage
-::: ngio.core.NgffImage