Merge pull request #134 from oesteban/docs/comment-notebooks-2

ENH: Add more comprehensive comments to notebook

Author: oesteban

docs/notebooks/02_afni_deoblique.ipynb

@@ -9,7 +9,15 @@
     "This notebook explores the implementation of *deobliquing* operations in AFNI, in order to be able to correctly manipulate transforms generated by the tool, and to produce transforms that can be correctly applied with AFNI.\n",
     "Most of the preparation comes from the previous notebook.\n",
     "\n",
-    "### Preparation"
+    "This notebook is the test bed for resolving [issue #45](https://github.com/poldracklab/nitransforms/issues/45)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Preamble\n",
+    "Prepare a Python environment and use a temporal directory for the outputs. After that, fetch the actual file from NiBabel documentation."
    ]
   },
   {
@@ -72,6 +80,14 @@
     "!wget https://nipy.org/nibabel/_downloads/62985f4c43f499609fa65cb2eb955b79/someones_anatomy.nii.gz"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Load in the image\n",
+    "Let's first visualize the example image, and retain some copies of the original header and affine."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 78,
@@ -109,6 +125,14 @@
     "nii.orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Generating variants\n",
+    "Playing with the affine header and the data array ordering of axes and elements we generate several versions of the dataset with different orientations (LAS, LPS, oblique, LPS oblique)."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 79,
@@ -148,6 +172,14 @@
     "lpsnew.to_filename('someones_anatomy_lpsrot.nii.gz')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Print affines of interest\n",
+    "Output some affines that we will want to compare to their counterparts generated by AFNI and stored in the NIfTI header"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 194,
@@ -208,7 +240,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Run `3dWarp -deoblique`"
+    "### Run `3dWarp -deoblique`\n",
+    "Generate one example image after \"deobliquing\", to then see if we can generate equivalent composite transforms"
    ]
   },
   {
@@ -260,6 +293,15 @@
     "Warp(in_file='someones_anatomy_rot.nii.gz', deoblique=True, verbose=True, out_file='deob.nii.gz').run()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Generating AFNI's \"deobliquing\" matrices\n",
+    "\n",
+    "Based on the image's information, we need to reconstruct AFNI's `WARPDRIVE_MATVEC_FOR_000000` affine, and then check that the results of applying such a matrix ends in the same outcome with AFNI and NiTransforms tools."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 204,
@@ -302,7 +344,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Inspecting affines and headers"
+    "### Inspecting affines and headers\n",
+    "Generate a rotation affine to apply on the original affine of an image, and try to reconstruct the inverse of it as AFNI calculates it.\n",
+    "\n",
+    "The following cells are just prior information useful for when we arrive to the next section"
    ]
   },
   {
@@ -1043,7 +1088,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Reverse-engineering matrix compositions of oblique datasets"
+    "### Reverse-engineering matrix compositions of oblique datasets\n",
+    "Calculating AFNI's affines based on the oblique image information"
    ]
   },
   {
@@ -1098,6 +1144,14 @@
     "print(R)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Visually test whether we correctly apply dual transforms with both tools\n",
+    "Load images generated with AFNI and with NiTransforms to check whether NiTransforms is operating as expected"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 195,
@@ -1152,6 +1206,13 @@
     "# nb.load('moved-affine-oblique-inv-T-for-master.nii.gz').orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If both derivatives are resampled in the same space, the following figure should be almost (or fully) blank."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 196,
@@ -1184,13 +1245,6 @@
     "deob = nb.load('deob.nii.gz')\n",
     "nb.Nifti1Image(np.abs(deob.get_fdata() - nb.load('deob-for2.nii.gz').get_fdata()), deob.affine, deob.header).orthoview()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {