add explanation

Author: Josh-Talks

example/model_usage.ipynb

@@ -17,38 +17,39 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 0. Activate human readable output error messages and load dependencies"
+    "## Activate human readable output error messages and load dependencies"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 0.1. Install necessary dependencies"
+    "### Running local"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "try:\n",
-    "    import matplotlib\n",
-    "    import torch\n",
+    "If you are running the notebook locally you need to pip install the following dependencies into your local environment. Make sure to restart your notebook kernel after installing dependencies.\n",
     "\n",
-    "    import bioimageio.core\n",
-    "except ImportError:\n",
-    "    %pip install bioimageio.core==0.6.7 torch==2.3.1 matplotlib==3.9.0"
+    "```console\n",
+    "pip install bioimageio.core==0.8.0 torch==2.5.1 matplotlib==3.10.1\n",
+    "```"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 0.2.Enable pretty_validation_errors\n",
-    "\n",
-    "This function displays validation errors in a human readable format."
+    "### Running in colab"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you are running this notebook through colab, there is no need to install dependencies manually, just run the following cell."
    ]
   },
   {
@@ -57,18 +58,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from bioimageio.spec.pretty_validation_errors import (\n",
-    "    enable_pretty_validation_errors_in_ipynb,\n",
-    ")\n",
+    "import os\n",
     "\n",
-    "enable_pretty_validation_errors_in_ipynb()"
+    "# install dependencies if running in colab\n",
+    "if os.getenv(\"COLAB_RELEASE_TAG\"):\n",
+    "    %pip install bioimageio.core==0.8.0 torch==2.5.1 matplotlib==3.10.1"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 0.3. Load general dependencies"
+    "### Install necessary dependencies"
    ]
   },
   {
@@ -77,7 +78,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Load general dependencies\n",
+    "import torch\n",
     "from pprint import pprint\n",
     "\n",
     "import matplotlib.pyplot as plt\n",
@@ -86,6 +87,14 @@
     "\n",
     "from bioimageio.spec.utils import download\n",
     "\n",
+    "import bioimageio.core\n",
+    "\n",
+    "from bioimageio.spec.pretty_validation_errors import (\n",
+    "    enable_pretty_validation_errors_in_ipynb,\n",
+    ")\n",
+    "\n",
+    "# Improve readiblity of validation errors\n",
+    "enable_pretty_validation_errors_in_ipynb()\n",
     "\n",
     "# Function to display input and prediction output images\n",
     "def show_images(sample_tensor, prediction_tensor):\n",
@@ -119,14 +128,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 1. Load a model"
+    "## Load a model"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 1.1 Inspect available models in the Bioimage Model Zoo"
+    "### Inspect available models in the Bioimage Model Zoo"
    ]
   },
   {
@@ -140,7 +149,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 1.2 Load model from the BioImage Model Zoo"
+    "### Load model from the BioImage Model Zoo"
    ]
   },
   {
@@ -151,7 +160,9 @@
     "\n",
     "Both of these options may be version specific (\"affable-shark/1\" or a version specific [__Zenodo__](https://zenodo.org/) backup [__DOI__](https://doi.org/)).\n",
     "\n",
-    "Alternatively, any rdf.yaml source, single file or in a .zip, may be loaded by providing its __local path__ or __URL__."
+    "Alternatively, any rdf.yaml source, single file or in a .zip, may be loaded by providing its __local path__ or __URL__.\n",
+    "\n",
+    "**Note** -- For more detailed information about loading a model, inspecting a model's metadata and creating your own model visit [bioimageio.spec package example notebook](https://github.com/bioimage-io/spec-bioimage-io/blob/main/example/load_model_and_create_your_own.ipynb)."
    ]
   },
   {
@@ -160,16 +171,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "BMZ_MODEL_ID = \"\"  # \"affable-shark\"\n",
-    "BMZ_MODEL_DOI = \"\"  # \"10.5281/zenodo.6287342\"\n",
-    "BMZ_MODEL_URL = \"https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/affable-shark/draft/files/rdf.yaml\""
+    "model_source = \"affable-shark\"\n",
+    "#model_source = \"10.5281/zenodo.6287342\"\n",
+    "#model_source = \"https://uk1s3.embassy.ebi.ac.uk/public-datasets/bioimage.io/affable-shark/draft/files/rdf.yaml\""
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`load_description` is a function of the `bioimageio.spec` package, but as it is a sub-package of `bioimageio.core` it can also be called from it by `bioimageio.core.load_description`.\n",
+    "`load_model_description` is a function of the `bioimageio.spec` package, but as it is a sub-package of `bioimageio.core` it can also be called from it by `bioimageio.core.load_model_description`.\n",
     "\n",
     "To learn more about the functionalities of the `bioimageio.spec` package, see the [bioimageio.spec package example notebook](https://github.com/bioimage-io/spec-bioimage-io/blob/main/example/load_model_and_create_your_own.ipynb), also available as a [Google Colab](https://colab.research.google.com/github/bioimage-io/spec-bioimage-io/blob/main/example/load_model_and_create_your_own.ipynb) notebook."
    ]
@@ -180,95 +191,47 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from bioimageio.core import load_description\n",
-    "\n",
-    "# Load the model description\n",
-    "# ------------------------------------------------------------------------------\n",
-    "if BMZ_MODEL_ID != \"\":\n",
-    "    model = load_description(BMZ_MODEL_ID)\n",
-    "    print(\n",
-    "        f\"\\nThe model '{model.name}' with ID '{BMZ_MODEL_ID}' has been correctly loaded.\"\n",
-    "    )\n",
-    "elif BMZ_MODEL_DOI != \"\":\n",
-    "    model = load_description(BMZ_MODEL_DOI)\n",
-    "    print(\n",
-    "        f\"\\nThe model '{model.name}' with DOI '{BMZ_MODEL_DOI}' has been correctly loaded.\"\n",
-    "    )\n",
-    "elif BMZ_MODEL_URL != \"\":\n",
-    "    model = load_description(BMZ_MODEL_URL)\n",
-    "    print(\n",
-    "        f\"\\nThe model '{model.name}' with URL '{BMZ_MODEL_URL}' has been correctly loaded.\"\n",
-    "    )\n",
-    "else:\n",
-    "    print(\"\\nPlease specify a model ID, DOI or URL\")\n",
-    "\n",
-    "if \"draft\" in BMZ_MODEL_ID or \"draft\" in BMZ_MODEL_DOI or \"draft\" in BMZ_MODEL_URL:\n",
-    "    print(\n",
-    "        f\"\\nThis is the DRAFT version of '{model.name}'. \\nDraft versions have not been reviewed by the Bioimage Model Zoo Team and may contain harmful code. Run with caution.\"\n",
-    "    )"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### 1.3 Inspect the model metadata\n",
+    "from bioimageio.core import load_model_description\n",
+    "from bioimageio.core import test_model\n",
     "\n",
-    "Let's inspect all the model metadata. For a step-by-step inspection refer to [bioimageio.spec package example notebook](https://github.com/bioimage-io/spec-bioimage-io/blob/main/example/load_model_and_create_your_own.ipynb)."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "pprint(model)"
+    "model = load_model_description(model_source)\n",
+    "test_summary = test_model(model) #Test model to check environment compatibility  \n",
+    "assert test_summary.status == \"passed\", test_summary.display() "
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "print(f\"\\n Covers of the model '{model.name}' are: \")\n",
-    "for cover in model.covers:\n",
-    "    cover_data = imread(download(cover).path)\n",
-    "    plt.figure(figsize=(10, 10))\n",
-    "    plt.imshow(cover_data)\n",
-    "    plt.xticks([])\n",
-    "    plt.yticks([])\n",
-    "    plt.show()"
+    "## Running a prediction"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 2. Test the model"
+    "`bioimageio.core` implements the functionality to run a prediction with models described in the `bioimage.io` format.\n",
+    "\n",
+    "This includes functions to run predictions on `numpy.ndarray`/`xarray.DataArray` as input and convenience functions to run predictions for images stored on disc."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The `bioimageio.core.test_model` function can be used to fully test the model.\n",
-    "This is done by running the predicition on the test input(s) and checking that they agree with the test output(s) provided in the model documentation.\n",
+    "### `predict` function \n",
+    "\n",
+    "The most direct way to run a model prediction is using the `bioimageio.core` convenience function `predict`, to which you pass the model you want to predict with and the input you want to predict on, along with optional arguments with default values. The input can be a range of types including; `numpy.ndarray`, `xarray.DataArray`, bioimageio `Tensor` or `pathlib.Path` to data. The union of all these types are contained within the `TensorSource` object.\n",
     "\n",
-    "This test should be run before using the model to ensure that it works properly.\n",
+    "`bioimageio.core.Tensors/xarray.DataArrays` are like numpy arrays, but they have annotated axes.\n",
     "\n",
-    "----\n",
+    "However, sometimes a model requires multiple inputs to be passed in at once (e.g a raw data input and a mask input). To easily facilitate this inputs can be passed in as a mapping between input id and `TensorSource`. For example defining mulitple `numpy.ndarray` inputs could be done manually done as follows:\n",
     "\n",
-    "`bioimageio.core.test_model` returns a validation dictionary with 'status'='passed'/'failed' and other detailed information that can be inspected by calling `.display()` on it.\n",
+    "```console\n",
+    "inputs = {\"raw_input\": np.array([1,2,3]), \"mask_input\": np.array()}\n",
+    "```\n",
     "\n",
-    "The validation summary will indicate:\n",
-    "- the versions of the `bioimageio.spec` and `bioimageio.core` libraries used to run the validation\n",
-    "- the status of several validation steps\n",
-    "    - ✔️: Success\n",
-    "    - 🔍: information about the validation context\n",
-    "    - ⚠: Warning\n",
-    "    - ❌: Error"
+    "To make things more convinent multiple inputs can instead be passed via a bioimageio `Sample` object"
    ]
   },
   {
@@ -277,28 +240,22 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from bioimageio.core import test_model\n",
+    "from bioimageio.core import predict  # , predict_many\n",
+    "from bioimageio.core import Sample\n",
     "\n",
-    "test_summary = test_model(model)\n",
-    "test_summary.display()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## 3. Running a prediction"
+    "# predict_many(model=model, inputs=[sample])\n",
+    "\n",
+    "prediction: Sample = predict(model=model, inputs=sample)\n",
+    "\n",
+    "# show the prediction result\n",
+    "show_images(sample, prediction)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`bioimageio.core` implements the functionality to run a prediction with models described in the `bioimage.io` format.\n",
-    "\n",
-    "This includes functions to run predictions on `numpy.ndarray`/`xarray.DataArray` as input and convenience functions to run predictions for images stored on disc.\n",
-    "\n",
-    "### 3.1. Load the test image and convert into a tensor"
+    "### Load the test image and convert into a tensor"
    ]
   },
   {
@@ -544,7 +501,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "bioimageio-core",
+   "display_name": "core",
    "language": "python",
    "name": "python3"
   },
@@ -558,7 +515,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.19"
+   "version": "3.12.10"
   }
  },
  "nbformat": 4,