Skip to content

Commit

Permalink
update the basic usage notebook
Browse files Browse the repository at this point in the history
  • Loading branch information
@lorenzocerrone
lorenzocerrone committed Nov 14, 2024
1 parent 7b8b708 commit 72c0832
Showing 1 changed file with 135 additions and 27 deletions.
162 changes: 135 additions & 27 deletions docs/notebooks/basic_usage.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,14 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Basic Usage\n",
"# OME-Zarr Image Exploration\n",
"\n",
"In this notebook we will show how to use the 'ngffImage' class to manage a OME-NGFF image.\n",
"In this notebook we will show how to use the 'NgffImage' class to explore and manage an OME-NGFF image.\n",
"\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",
Expand All @@ -20,7 +22,7 @@
"## NgffImage\n",
"\n",
"The `NgffImage` provides a high-level interface to read, write and manipulate NGFF images.\n",
"A `NgffImage` can be created from a storelike object (e.g. a path to a directory or a zarr store) or from a `zarr.Group` object. "
"A `NgffImage` can be created from a storelike object (e.g. a path to a directory, or a url) or from a `zarr.Group` object. "
]
},
{
Expand All @@ -30,19 +32,24 @@
"outputs": [],
"source": [
"from ngio.core import NgffImage\n",
"from ngio.core.utils import get_fsspec_http_store\n",
"\n",
"# Ngio can stream data from any fsspec-compatible store\n",
"url = \"https://raw.githubusercontent.com/fractal-analytics-platform/fractal-ome-zarr-examples/refs/heads/main/v04/20200812-CardiomyocyteDifferentiation14-Cycle1_B_03_mip.zarr/\"\n",
"store = get_fsspec_http_store(url)\n",
"ngff_image = NgffImage(store, \"r\")"
"path = \"../../data/20200812-CardiomyocyteDifferentiation14-Cycle1_mip.zarr/B/03/0\"\n",
"ngff_image = NgffImage(path, \"r\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `ngff_image` contains several attributes and methods to interact with the `OME-NGFF` (`OME-Zarr`) file on the storage."
"\n",
"The `ngff_image` object provides a high-level interface to read, write and manipulate OME-Zarr images.\n",
"\n",
"Print the image will show some overview information like:\n",
"* The path to the image\n",
"* The multiscale pyramid paths\n",
"* The labels contained in the image\n",
"* The tables contained in the imag"
]
},
{
Expand All @@ -51,12 +58,23 @@
"metadata": {},
"outputs": [],
"source": [
"# Explore object metadata\n",
"print(ngff_image)\n",
"image = ngff_image.get_image()\n",
"print(image)\n",
"nuclei = ngff_image.labels.get_label(\"nuclei\")\n",
"print(nuclei)\n"
"print(ngff_image)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"From the NgffImage object, you can access the image data as a numpy ar"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"From the `NgffImage` object we can easily access access the image data (at any resolution level), the labels and the tables."
]
},
{
Expand All @@ -78,17 +96,69 @@
"\n",
"# 1. Get image from highest resolution (default)\n",
"image = ngff_image.get_image()\n",
"print(f\"{image.shape=}\")\n",
"print(f\"{image.pixel_size=}\")\n",
"print(image)\n",
"\n",
"# 2. Get image from a specific level using the path keyword\n",
"print(f\"{image.shape=}\")\n",
"print(f\"{image.pixel_size=}\")\n",
"image = ngff_image.get_image(path=\"1\")\n",
"print(image)\n",
"\n",
"# 3. Get image from a specific pixel size using the pixel_size keyword\n",
"image = ngff_image.get_image(pixel_size=PixelSize(x=0.65, y=0.65, z=1))\n",
"print(f\"{image.shape=}\")\n",
"print(f\"{image.pixel_size=}\")"
"print(image)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The `Image` object provides a high-level interface to read and write image data at a specific resolution level."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"print(\"Shape\", image.shape)\n",
"print(\"Axes\", image.axes_names)\n",
"print(\"PixelSize\", image.pixel_size)\n",
"print(\"Dimensions\", image.dimensions)\n",
"print(\"Channel Names\", image.channel_labels)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Get data as a numpy array or a dask array\n",
"data = image.get_array(c=0, mode=\"numpy\")\n",
"print(data)\n",
"\n",
"dask_data = image.get_array(c=0, mode=\"dask\")\n",
"dask_data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"`ngio` design is to always provide the data in a canonical axis order (`t`, `c`, `z`, `y`, `x`) no matter what is the order on disk. \n",
"The `Image` object provides methods to access the data in this order. \n",
"If you want to access data or metadata in the on-disk order, you can by using `on_disk_{method_name}` methods.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"print(\"On-disk shape\", image.on_disk_shape)\n",
"print(\"On-disk array\", image.on_disk_array)\n",
"print(\"On-disk dask array\", image.on_disk_dask_array)"
]
},
{
Expand All @@ -97,7 +167,7 @@
"source": [
"## Labels\n",
"\n",
"The `NgffImage` can also be used to load labels from a `OME-NGFF` file."
"The `NgffImage` can also be used to load labels from a `OME-NGFF` file and behave similarly to the `Image` object."
]
},
{
Expand All @@ -109,8 +179,7 @@
"print(\"List of Labels: \", ngff_image.labels.list())\n",
"\n",
"label_nuclei = ngff_image.labels.get_label(\"nuclei\", path=\"0\")\n",
"print(f\"{label_nuclei.shape=}\")\n",
"print(f\"{label_nuclei.pixel_size=}\")"
"print(label_nuclei)"
]
},
{
Expand Down Expand Up @@ -165,6 +234,30 @@
"roi_table.table"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Rois can be used to index image and label data."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import matplotlib.pyplot as plt\n",
"\n",
"# Plotting a single ROI\n",
"roi = roi_table.get_roi(\"FOV_1\")\n",
"roi_data = image.get_array_from_roi(roi, c=0, mode=\"numpy\")\n",
"plt.title(\"ROI: FOV_1\")\n",
"plt.imshow(roi_data[0], cmap=\"gray\")\n",
"plt.axis(\"off\")\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand All @@ -184,18 +277,33 @@
"outputs": [],
"source": [
"new_ngff_image = ngff_image.derive_new_image(\"../../data/new_ome.zarr\", name=\"new_image\")\n",
"print(new_ngff_image)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Steam an NgffImage over HTTP\n",
"\n",
"print(f\"{new_ngff_image.store=}\")\n",
"print(f\"{new_ngff_image.levels_paths=}\")\n",
"print(f\"{new_ngff_image.num_levels=}\")"
"The `NgffImage` class can also be used to stream an image over HTTP. This is useful when the image is stored on a remote server and you want to access it without downloading the entire image. All features of the `NgffImage` class are available when streaming an image over HTTP (besides anything that requires writing to the image)."
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
"source": [
"from ngio.core.utils import get_fsspec_http_store\n",
"\n",
"# Ngio can stream data from any fsspec-compatible store\n",
"url = \"https://raw.githubusercontent.com/fractal-analytics-platform/fractal-ome-zarr-examples/refs/heads/main/v04/20200812-CardiomyocyteDifferentiation14-Cycle1_B_03_mip.zarr/\"\n",
"store = get_fsspec_http_store(url)\n",
"ngff_image = NgffImage(store, \"r\")\n",
"\n",
"print(ngff_image)"
]
}
],
"metadata": {
Expand Down

0 comments on commit 72c0832

Please sign in to comment.