update explanations

Author: Josh-Talks

example/model_usage.ipynb

@@ -74,7 +74,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 36,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -248,7 +248,7 @@
     "\n",
     "The most direct way to run a model prediction is using the `bioimageio.core.predict` function, to which you pass the model you want to predict with and the input you want to predict on, along with optional keyword arguments. The input can be given as a `numpy.ndarray`, `xarray.DataArray`, bioimageio `Tensor` or `pathlib.Path` to an image (`TensorSource`).\n",
     "\n",
-    "`bioimageio.core.Tensors/xarray.DataArrays` are like numpy arrays, but they have annotated axes. The axes are used to validate that the axes of the input image match the axes expected by the model."
+    "`bioimageio.core.Tensors/xarray.DataArrays` are like numpy arrays, but they have annotated axes. The axes are used to match the input image to what the model expects. You can create a Tensor instance explicitly if you want to assign a specific axis order."
    ]
   },
   {
@@ -403,7 +403,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Alternatively, instead of directly setting input as a Mapping[TensorId, TensorSource] we can set input to be a `Sample` instance. Conceptually a `Sample` is similar but provides the additional functionality of having precomputed sample statistics along with helper functions to automatically create a `Sample` for a given model.\n",
+    "Alternatively, instead of directly setting input as a Mapping[TensorId, TensorSource] we can set input to be a `Sample` instance. Inside `predict` a `Sample` will actually be created no matter the given input type. The `Sample` instance can be created explicitly for a given model using the helper function `create_sample_for_model`. Another useful functionality of `Sample` is that it can keep track of precomputed sample and dataset statistics, which certain preprocessing steps require.\n",
     "\n",
     "In order to create a `Sample` we first create a `Tensor` (light wrapper around an `xarray.DataArray`) from the test input image, adding annotated axes."
    ]
@@ -439,24 +439,29 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 17,
+   "execution_count": 37,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "Sample(members={'raw': <bioimageio.core.tensor.Tensor object at 0x312674c80>}, stat={}, id='sample-from-numpy')"
+       "Sample(members={'raw': <bioimageio.core.tensor.Tensor object at 0x312675dc0>}, stat={DatasetMean(member_id='raw', scope='dataset', name='mean', axes=None): 123.456}, id='sample-from-numpy')"
       ]
      },
-     "execution_count": 17,
+     "execution_count": 37,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "from bioimageio.core import Sample\n",
+    "from bioimageio.core.stat_measures import DatasetMean\n",
     "\n",
-    "sample = Sample(members={\"raw\": test_input_tensor}, stat={}, id=\"sample-from-numpy\")\n",
+    "sample = Sample(\n",
+    "    members={\"raw\": test_input_tensor}, \n",
+    "    stat={DatasetMean(member_id=TensorId(\"raw\")): 123.456}, # Example mean value\n",
+    "    id=\"sample-from-numpy\"\n",
+    ")\n",
     "\n",
     "sample"
    ]
@@ -626,9 +631,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### prediciton pipeline (Advanced)\n",
+    "### Prediciton pipeline (Advanced)\n",
     "\n",
-    "The `prediction_pipeline` function is used to run a prediction with a given model.\n",
+    "The `prediction_pipeline` function is used to run a prediction with a given model and provides more finegrained control for model prediction.\n",
     "\n",
     "It applies the __pre-processing__, if indicated in the model rdf.yaml, runs __inference__ with the model and applies the __post-processing__, again if specified in the model rdf.yaml.\n",
     "\n",
@@ -707,7 +712,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 30,
    "metadata": {},
    "outputs": [
     {
@@ -748,16 +753,9 @@
     "\n",
     "    np_output_list.append(output_array)\n",
     "\n",
-    "plt.imshow(np_input_list[0])\n",
+    "_ = plt.imshow(np_input_list[0])\n",
     "plt.show()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {