ngio 0.3.5__tar.gz → 0.4.0a1__tar.gz

{ngio-0.3.5 → ngio-0.4.0a1}/.github/workflows/build_docs.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
       - name: 🐍 Set up Python

{ngio-0.3.5 → ngio-0.4.0a1}/.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
     # included in the sdist (unless explicitly excluded)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - run: pipx run check-manifest
 
   test:
@@ -37,7 +37,7 @@ jobs:
         platform: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: 🐍 Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -98,7 +98,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0
 

{ngio-0.3.5 → ngio-0.4.0a1}/.pre-commit-config.yaml

@@ -9,19 +9,19 @@ ci:
 
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.18
+    rev: v0.24.1
     hooks:
       - id: validate-pyproject
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1
+    rev: v1.36.2
     hooks:
       - id: typos
         #args: [--force-exclude]  # omitting --write-changes
         args: [--force-exclude, --write-changes]
 
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.9.6
+    rev: v0.12.12
     hooks:
       - id: ruff
         args: [--fix]  # may also add '--unsafe-fixes'
@@ -37,7 +37,7 @@ repos:
   #      #   - numpy
 
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.7.1
+    rev: 0.8.1
     hooks:
       - id: nbstripout
 

ngio-0.4.0a1/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [v0.4.0a1]
+
+### Features
+
+- add support for time in rois and roi-tables
+- Building masking roi tables expanded to time series data
+- add experimental support for Iterators
+- add support for rescaling on-the-fly masks for masked images
+
+### API Changes
+
+- The image-like `get_*` api have been slightly changed. Now if a single int is passed as slice_kwargs, it is interpreted as a single index. So the dimension is automatically squeezed.
+- Remove the `get_*_delayed` methods, now data cam only be loaded as numpy or dask array.Use the `get_as_dask` method instead, which returns a dask array that can be used with dask delayed.
+- A new model for channel selection is available. Now channels can be selected by name, index or with `ChannelSelectionModel` object.
+- Change `table_name` keyword argument to `name` for consistency in all table concatenation functions, e.g. `concatenate_image_tables`,  `concatenate_image_tables_as`, etc.
+- Change to `Dimension` class. `get_shape` and `get_canonical_shape` have been removed, `get` uses new keyword arguments `default` instead of `strict`.
+- Image like objects now have a more clean API to load data. Instead of `get_array` and `set_array`, they now use `get_as_numpy`, and `get_as_dask` for delayed arrays.
+- Also for `get_roi` now specific methods are available. For ROI objects, the `get_roi_as_numpy`, and `get_roi_as_dask` methods.
+- Table ops moved to `ngio.images`
+- Make `label` an explicit attribute in `Roi` objects.
+
+### Table specs
+
+- add `t_second` and `len_t_second` to ROI tables and masking ROI tables
+
+### Bug Fixes
+
+- improve type consistency and remove non-necessary "type: ignore"
+
+## [v0.3.5]
+
+- Remove path normalization for images in wells. While the spec requires paths to be alphanumeric, this patch removes the normalization to allow for arbitrary image paths.
+
+## [v0.3.4]
+
+- allow to write as `anndata_v1` for backward compatibility with older ngio versions.
+
+## [v0.3.3]
+
+### Chores
+
+- improve dataset download process and streamline the CI workflows
+
+## [v0.3.2]
+
+### API Changes
+
+- change table backend default to `anndata_v1` for backward compatibility. This will be chaanged again when ngio `v0.2.x` is no longer supported.
+
+### Bug Fixes
+
+- fix [#13](https://github.com/BioVisionCenter/fractal-converters-tools/issues/13) (converters tools)
+- fix [#88](https://github.com/BioVisionCenter/ngio/issues/88)

{ngio-0.3.5 → ngio-0.4.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.3.5
+Version: 0.4.0a1
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/BioVisionCenter/ngio
 Project-URL: repository, https://github.com/BioVisionCenter/ngio
@@ -38,11 +38,13 @@ Requires-Dist: napari; extra == 'dev'
 Requires-Dist: notebook; extra == 'dev'
 Requires-Dist: pdbpp; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pympler; extra == 'dev'
 Requires-Dist: pyqt5; extra == 'dev'
 Requires-Dist: rich; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: scikit-image; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: griffe-typingdoc; extra == 'docs'
 Requires-Dist: markdown-exec[ansi]; extra == 'docs'
 Requires-Dist: matplotlib; extra == 'docs'
 Requires-Dist: mike; extra == 'docs'

ngio-0.4.0a1/docs/api/hcs.md

@@ -0,0 +1,17 @@
+# HCS API Documentation
+
+## Open a Plate
+
+::: ngio.open_ome_zarr_plate
+
+## ngio.OmeZarrPlate Class Reference
+
+::: ngio.OmeZarrPlate
+
+## Open a Well
+
+::: ngio.open_ome_zarr_well
+
+## ngio.OmeZarrWell Class Reference
+
+::: ngio.OmeZarrWell

ngio-0.4.0a1/docs/api/images.md

@@ -0,0 +1,17 @@
+# Images Like: API Documentation
+
+## Open an Image
+
+::: ngio.open_image
+
+## ngio.Image Class Reference
+
+::: ngio.Image
+
+## Open a Label
+
+::: ngio.open_label
+
+## ngio.Label Class Reference
+
+::: ngio.Label

ngio-0.4.0a1/docs/api/ngio/common.md

@@ -0,0 +1,3 @@
+# ngio.common API documentation
+
+::: ngio.common

ngio-0.4.0a1/docs/api/ngio/hcs.md

@@ -0,0 +1,3 @@
+# ngio.hcs API documentation
+
+::: ngio.hcs

ngio-0.4.0a1/docs/api/ngio/images.md

@@ -0,0 +1,3 @@
+# ngio.images API documentation
+
+::: ngio.images

ngio-0.4.0a1/docs/api/ngio/ngio.md

@@ -0,0 +1,3 @@
+# ngio API documentation
+
+::: ngio

ngio-0.4.0a1/docs/api/ngio/tables.md

@@ -0,0 +1,3 @@
+# ngio.tables API documentation
+
+::: ngio.tables

ngio-0.4.0a1/docs/api/ngio/utils.md

@@ -0,0 +1,3 @@
+# ngio.utils
+
+::: ngio.utils

ngio-0.4.0a1/docs/api/ome_zarr_container.md

@@ -0,0 +1,14 @@
+# OmeZarrContainer: API Documentation
+
+## Open an OME-Zarr Container
+
+::: ngio.open_ome_zarr_container
+
+## Create an OME-Zarr Container
+
+::: ngio.create_empty_ome_zarr
+::: ngio.create_ome_zarr_from_array
+
+## OmeZarrContainer Class
+
+::: ngio.OmeZarrContainer

ngio-0.4.0a1/docs/api/tables.md

@@ -0,0 +1 @@
+# Ngio Tables API Documentation

{ngio-0.3.5 → ngio-0.4.0a1}/docs/getting_started/1_ome_zarr_containers.md

@@ -81,8 +81,8 @@ Examples of the OME-Zarr metadata access:
     ```
     The metadata object contains all the information about the image, for example, the channel labels:
     ```pycon exec="true" source="console" session="get_started"
-    >>> metadata.channel_labels
-    >>> print(metadata.channel_labels) # markdown-exec: hide
+    >>> metadata.channels_meta.channel_labels
+    >>> print(metadata.channels_meta.channel_labels) # markdown-exec: hide
     ```
 
 ## Accessing images / labels / tables

{ngio-0.3.5 → ngio-0.4.0a1}/docs/getting_started/2_images.md

@@ -72,29 +72,31 @@ Once you have the `Image` object, you can access the image data as a:
 
 === "Numpy Array"
     ```pycon exec="true" source="console" session="get_started"
-    >>> data = image.get_array() # Get the image as a numpy array
+    >>> data = image.get_as_numpy() # Get the image as a numpy array
     >>> data.shape, data.dtype
     >>> print(data.shape, data.dtype) # markdown-exec: hide
     ```
 
 === "Dask Array"
     ```pycon exec="true" source="console" session="get_started"
-    >>> dask_array = image.get_array(mode="dask") # Get the image as a dask array
+    >>> dask_array = image.get_as_dask() # Get the image as a dask array
     >>> dask_array
     >>> print(dask_array) # markdown-exec: hide
     ```
 
-=== "Dask Delayed"
+=== "Legacy"
+    A generic `get_array` method is still available for backwards compatibility.
+
     ```pycon exec="true" source="console" session="get_started"
-    >>> dask_delayed = image.get_array(mode="delayed") # Get the image as a dask delayed object
-    >>> dask_delayed
-    >>> print(dask_delayed) # markdown-exec: hide
+    >>> data = image.get_array(mode="numpy") # Get the image as a numpy or dask or delayed object
+    >>> data.shape, data.dtype
+    >>> print(data.shape, data.dtype) # markdown-exec: hide
     ```
 
-The `get_array` can also be used to slice the image data, and query specific axes in specific orders:
+The `get_as_*` can also be used to slice the image data, and query specific axes in specific orders:
 
 ```pycon exec="true" source="console" session="get_started"
->>> image_slice = image.get_array(c=0, x=slice(0, 128), axes_order=["t", "z", "y", "x", "c"]) # Get a specific channel and axes order
+>>> image_slice = image.get_as_numpy(c=0, x=slice(0, 128), axes_order=["t", "z", "y", "x", "c"]) # Get a specific channel and axes order
 >>> image_slice.shape
 >>> print(image_slice.shape) # markdown-exec: hide
 ```
@@ -111,7 +113,7 @@ A minimal example of how to use the `get_array` and `set_array` methods:
 
 ```python exec="true" source="material-block" session="get_started"
 # Get the image data as a numpy array
-data = image.get_array(c=0, x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
+data = image.get_as_numpy(c=0, x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
 
 # Modify the image data
 some_function = lambda x: x # markdown-exec: hide

{ngio-0.3.5 → ngio-0.4.0a1}/docs/getting_started/3_tables.md

@@ -38,7 +38,7 @@ Ngio supports three types of tables: `roi_table`, `feature_table`, and `masking_
     image_data = image_3.get_array(c=0)
     image_data = np.squeeze(image_data)
     roi = roi_table.get("FOV_1")
-    roi = roi.to_pixel_roi(pixel_size=image_3.pixel_size, dimensions=image_3.dimensions)
+    roi = roi.to_roi_pixels(pixel_size=image_3.pixel_size, dimensions=image_3.dimensions)
     #label_3 = ome_zarr_container.get_label("nuclei", pixel_size=image_3.pixel_size)
     #label_data = label_3.get_array()
     #label_data = np.squeeze(label_data)
@@ -98,12 +98,12 @@ Ngio supports three types of tables: `roi_table`, `feature_table`, and `masking_
     The `nuclei_ROI_table` contains the masks for the `nuclei` label in the image, and is indexed by the label id.
     ```pycon exec="true" source="console" session="get_started"
     >>> masking_table = ome_zarr_container.get_table("nuclei_ROI_table") # Get a mask table
-    >>> masking_table.get(1)
-    >>> print(masking_table.get(100)) # markdown-exec: hide
+    >>> masking_table.get_label(1)
+    >>> print(masking_table.get_label(100)) # markdown-exec: hide
     ```
     ROIs can be used to slice the image data:
     ```pycon exec="true" source="console" session="get_started"
-    >>> roi = masking_table.get(100)
+    >>> roi = masking_table.get_label(100)
     >>> roi_data = image.get_roi(roi)
     >>> roi_data.shape
     >>> print(roi_data.shape) # markdown-exec: hide
@@ -120,7 +120,7 @@ Ngio supports three types of tables: `roi_table`, `feature_table`, and `masking_
     cmap_array = np.random.rand(1000, 3)
     cmap_array[0] = 0
     cmap = ListedColormap(cmap_array)
-    roi = masking_table.get(100)
+    roi = masking_table.get_label(100)
     image_3 = ome_zarr_container.get_image(path="2")
     image_data = image_3.get_roi(roi, c=0)
     image_data = np.squeeze(image_data)

{ngio-0.3.5 → ngio-0.4.0a1}/docs/table_specs/backend.md

@@ -66,7 +66,7 @@ table.zarr          # Zarr group for the table
 
 The CSV backend is a plain text format that is widely used for tabular data. It is easy to read and write, and can be used across many different tools.
 
-The CSV backen in ngio follows closely the same specifications as the Parquet backend, with the following metadata:
+The CSV backend in ngio follows closely the same specifications as the Parquet backend, with the following metadata:
 
 ```json
 {

{ngio-0.3.5 → ngio-0.4.0a1}/docs/table_specs/table_types/masking_roi_table.md

@@ -31,5 +31,7 @@ Moreover the ROI table must include the following columns:
 
 - `x_micrometer`, `y_micrometer`, `z_micrometer`: the top-left corner coordinates of the ROI in micrometers.
 - `len_x_micrometer`, `len_y_micrometer`, `len_z_micrometer`: the size of the ROI in micrometers along each axis.
+- `label`: An integer column label associated with the ROI, which corresponds to a specific label in the label image. This can also be the table index key.
+- (Optional) `t_second` and `len_t_second`: the time coordinate of the ROI in seconds, and the length of the time coordinate in seconds. This is useful for multiplexing acquisitions.
 
 Additionally, each ROI can include the following optional columns: see [ROI Table](./roi_table.md).

{ngio-0.3.5 → ngio-0.4.0a1}/docs/table_specs/table_types/roi_table.md

@@ -33,6 +33,7 @@ Moreover the ROI table must include the following columns:
 
 Additionally, each ROI can include the following optional columns:
 
+- `t_second` and `len_t_second`: the time coordinate of the ROI in seconds, and the length of the time coordinate in seconds. This is useful for multiplexing acquisitions.
 - `x_micrometer_original`, `y_micrometer_original` and `z_micrometer_original` which are the original coordinates of the ROI in micrometers. These are typically used when the data is saved in different coordinates during conversion, e.g. to avoid overwriting data from overlapping ROIs.
 - `translation_x`, `translation_y` and `translation_z`, which are used during registration of multiplexing acquisitions.
 

ngio-0.4.0a1/docs/tutorials/create_ome_zarr.ipynb

@@ -0,0 +1,101 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "0",
+   "metadata": {},
+   "source": [
+    "# OME-Zarr Creation\n",
+    "\n",
+    "This is a minimal example of how to create an OME-Zarr image using `ngio`.\n",
+    "\n",
+    "This example is just a simple demonstration but for more complex conversion tasks please refer \n",
+    "to the converter tooling library [ome-zarr-converters-tools](https://github.com/BioVisionCenter/ome-zarr-converters-tools).\n",
+    "\n",
+    "Let's start by converting a sample image from `skimage` to OME-Zarr format."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import skimage\n",
+    "from matplotlib import pyplot as plt\n",
+    "\n",
+    "plt.imshow(skimage.data.human_mitosis(), cmap=\"gray\")\n",
+    "plt.axis(\"off\")\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from ngio import create_ome_zarr_from_array\n",
+    "\n",
+    "ome_zarr = create_ome_zarr_from_array(\n",
+    "    store=\"./data/human_mitosis.zarr\",\n",
+    "    array=skimage.data.human_mitosis(),\n",
+    "    xy_pixelsize=0.1,  # Just a guess\n",
+    ")\n",
+    "ome_zarr"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3",
+   "metadata": {},
+   "source": [
+    "## Adding Rois to OME-Zarr\n",
+    "\n",
+    "Often, is useful to add ROIs to OME-Zarr images to be able to retrieve them later.  \n",
+    "This can be done using the `ngio` library as follows."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# create a roi for the whole image\n",
+    "roi_table = ome_zarr.build_image_roi_table(name=\"image_roi\")\n",
+    "ome_zarr.add_table(\"image_roi_table\", roi_table)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "dev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

ngio-0.4.0a1/docs/tutorials/feature_extraction.ipynb

@@ -0,0 +1,118 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Feature Extraction\n",
+    "\n",
+    "This sections will cover how to extract regionprops features from an image using `ngio`, `skimage`. Moreover we will also write the features to a table in the ome-zarr container.\n",
+    "\n",
+    "# Step 1: Open the OME-Zarr Container"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "\n",
+    "from ngio import open_ome_zarr_container\n",
+    "from ngio.utils import download_ome_zarr_dataset\n",
+    "\n",
+    "# Download the dataset\n",
+    "download_dir = Path(\".\").absolute().parent.parent / \"data\"\n",
+    "hcs_path = download_ome_zarr_dataset(\"CardiomyocyteTinyMip\", download_dir=download_dir)\n",
+    "image_path = hcs_path / \"B\" / \"03\" / \"0\"\n",
+    "\n",
+    "# Open the ome-zarr container\n",
+    "ome_zarr = open_ome_zarr_container(image_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Step 2: Compute the Regionprops Features"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "from skimage import measure\n",
+    "\n",
+    "from ngio.tables import FeatureTable\n",
+    "\n",
+    "# First we will need the image object and the FOVs table\n",
+    "nuclei = ome_zarr.get_label(\"nuclei\")\n",
+    "image_data = ome_zarr.get_image(pixel_size=nuclei.pixel_size).get_as_numpy(\n",
+    "    axes_order=[\"z\", \"y\", \"x\", \"c\"]\n",
+    ")\n",
+    "nuclei_data = nuclei.get_as_numpy(axes_order=[\"z\", \"y\", \"x\"])\n",
+    "\n",
+    "feat_table = measure.regionprops_table(\n",
+    "    label_image=nuclei_data,\n",
+    "    intensity_image=image_data,\n",
+    "    properties=[\"label\", \"area\", \"mean_intensity\", \"max_intensity\", \"min_intensity\"],\n",
+    ")\n",
+    "\n",
+    "feat_table = pd.DataFrame(feat_table)\n",
+    "feat_table = feat_table.set_index(\"label\")\n",
+    "\n",
+    "# Convert to a FeatureTable\n",
+    "feature_table = FeatureTable(table_data=feat_table, reference_label=\"nuclei\")\n",
+    "\n",
+    "# Save the Table in the ome-zarr container\n",
+    "ome_zarr.add_table(\"nuclei_regionprops\", feature_table)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Sanity Check: Read the Table back"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ome_zarr.get_table(\"nuclei_regionprops\").lazy_frame.collect()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "dev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}