DOC: Document the PET notebook

Document the PET notebook: add markdown cells explaining the steps.

Author: jhlegarreta

docs/notebooks/pet_motion_estimation.ipynb

@@ -1,20 +1,38 @@
 {
  "cells": [
   {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "4111cc1b-5123-407a-8ec6-56d65bc94bc4",
    "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "# Positron emission tomography (PET) data realignment example\n",
+    "\n",
+    "This example shows how to estimate the head motion of a PET dataset using\n",
+    "`NiFreeze`.\n",
+    "\n",
+    "The notebook uses the `sub-02` dataset that was generated synthetically from\n",
+    "a real PET dataset by adding random motion. The dataset\n",
+    "can be installed from [GIN G-node](https://gin.g-node.org/nipreps-data/tests-nifreeze):\n",
+    "\n",
+    "```\n",
+    "$ datalad install -g https://gin.g-node.org/nipreps-data/tests-nifreeze.git\n",
+    "```\n",
+    "\n",
+    "after which the environment variable `TEST_DATA_HOME` will need to be set to\n",
+    "point to the corresponding folder."
+   ],
+   "id": "e8a4c20508512623"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
    "outputs": [],
+   "execution_count": 1,
    "source": [
     "from os import getenv\n",
     "from pathlib import Path\n",
     "\n",
     "from nifreeze.data.pet import PET\n",
     "\n",
-    "# Install test data from gin.g-node.org:\n",
-    "#   $ datalad install -g https://gin.g-node.org/nipreps-data/tests-nifreeze.git\n",
-    "# and point the environment variable TEST_DATA_HOME to the corresponding folder\n",
     "DATA_PATH = Path(getenv(\"TEST_DATA_HOME\", str(Path.home() / \"nifreeze-tests\")))\n",
     "WORKDIR = Path.home() / \"tmp\" / \"nifreezedev\" / \"pet_data\"\n",
     "WORKDIR.mkdir(parents=True, exist_ok=True)\n",
@@ -30,7 +48,8 @@
     ")\n",
     "\n",
     "pet_dataset = PET.load(pet_file, json_file)"
-   ]
+   ],
+   "id": "a258948070bbc0c"
   },
   {
    "cell_type": "code",
@@ -53,6 +72,17 @@
     "pet_dataset"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## Model fitting and motion correction\n",
+    "\n",
+    "The relevant structure to model PET data is `nifreeze.model.PETModel`. We\n",
+    "instantiate it by providing it with the loaded PET dataset."
+   ],
+   "id": "22dd60dcdd65f09d"
+  },
   {
    "cell_type": "code",
    "execution_count": 4,
@@ -417,19 +447,35 @@
    "id": "d541ae17-8bf8-457a-8aeb-986a4324434a",
    "metadata": {},
    "outputs": [],
+   "source": "model.fit_predict(None)"
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
    "source": [
-    "model.fit_predict(None)"
-   ]
+    "Let's now ask the model for a prediction on the `midframe[2]` time point. By\n",
+    "calling `model.fit_predict` the model is fitted using all the available data,\n",
+    "and a prediction is requested on the time provided as the argument. By\n",
+    "default, the PET model employs a B-Spline based method for motion correction."
+   ],
+   "id": "fa33b648ed70d336"
   },
   {
    "cell_type": "code",
    "execution_count": 7,
    "id": "dee05183-57b5-46ed-811a-c0b26a53a386",
    "metadata": {},
    "outputs": [],
+   "source": "predicted = model.fit_predict(pet_dataset.midframe[2])"
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
    "source": [
-    "predicted = model.fit_predict(pet_dataset.midframe[2])"
-   ]
+    "We now save the uncorrected and corrected data so that we can visualize\n",
+    "the difference."
+   ],
+   "id": "c4985826e2d8bc54"
   },
   {
    "cell_type": "code",
@@ -451,6 +497,15 @@
     "nifti_img_after.to_filename(output_path_after)"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "Let's now visualize a number of axial, sagittal and coronal slices of the\n",
+    "uncorrected and corrected data."
+   ],
+   "id": "7dfb887dcc76aa65"
+  },
   {
    "cell_type": "code",
    "execution_count": 10,
@@ -2240,6 +2295,19 @@
     ")"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## Motion estimation\n",
+    "\n",
+    "We now want to have an estimate of the motion that the model corrects. We will\n",
+    "need to instantiate the `nifreeze.estimator.PETMotionEstimator`, which will\n",
+    "take an instance of the model. We will call `run` to get the parameters of the\n",
+    "affine transform estimation."
+   ],
+   "id": "95b6939bea2d1394"
+  },
   {
    "cell_type": "code",
    "execution_count": 13,
@@ -2431,6 +2499,15 @@
     "affines"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "Let's now visualize the estimated motion: we will plot the translation and\n",
+    "rotation components in the affine transform for each axis."
+   ],
+   "id": "991990094e4a07f3"
+  },
   {
    "cell_type": "code",
    "execution_count": 16,