Merge pull request #133 from oesteban/docs/comment-notebooks

DOC: Better document the ipython notebooks

Author: oesteban

docs/conf.py

@@ -222,3 +222,33 @@
 
 # -- Options for versioning extension ----------------------------------------
 scv_show_banner = True
+
+nbsphinx_prolog = """
+{% set docname = 'docs/' + env.doc2path(env.docname, base=None) %}
+
+.. raw:: html
+
+    <div class="admonition note">
+      This page was generated from
+      <a class="reference external" href="https://github.com/poldracklab/nitransforms/blob/master\
+/{{ docname|e }}">{{ docname|e }}</a>.
+      <script>
+        if (document.location.host) {
+          $(document.currentScript).replaceWith(
+            '<a class="reference external" ' +
+            'href="https://nbviewer.jupyter.org/url' +
+            (window.location.protocol == 'https:' ? 's/' : '/') +
+            window.location.host +
+            window.location.pathname.slice(0, -4) +
+            'ipynb">View in <em>nbviewer</em></a>.'
+          );
+        }
+      </script>
+    </div>
+
+"""
+
+# This is processed by Jinja2 and inserted after each notebook
+nbsphinx_epilog = """
+{% set docname = 'docs/notebooks' + env.doc2path(env.docname, base=None) %}
+"""

docs/notebooks/01_preparing_images.ipynb

@@ -4,7 +4,17 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Preparing images"
+    "## Preparing images\n",
+    "\n",
+    "This notebook uses the example NIfTI from NiBabel's documentation (\"`someones_anatomy.nii.gz`\") and creates several derived versions of it with different orientations, including oblique physical axes (i.e., the physical axes are rotated w.r.t. the canonical axes of the array), ordering of axes (e.g., RSA), and axis flips (e.g., LAS)."
+   ]
+  },
+  {
+   "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."
    ]
   },
   {
@@ -75,6 +85,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": 3,
@@ -112,6 +130,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": 4,
@@ -151,6 +177,15 @@
     "lpsnew.to_filename('someones_anatomy_lpsrot.nii.gz')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Quick test with AFNI's `3dWarp -deoblique`\n",
+    "AFNI `3dWarp` comes with a `-deoblique` option that can be interesting to double check whether the examples above are useful.\n",
+    "This example checks whether our *oblique* image's version is perceived as such by AFNI, and *realign* it with the canonical axes."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 28,
@@ -173,6 +208,13 @@
     "!3dWarp -deoblique -prefix deob.nii.gz someones_anatomy_rot.nii.gz"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "AFNI stores the actual rotation matrices of the *deoblique* operation as NIfTI header extensions:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 30,
@@ -419,6 +461,16 @@
     "print(nb.load('deob.nii.gz').header.extensions[0].get_content().decode())"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Testing the variants with *NiTransforms*, *AFNI*, *ANTs*, and *FSL*, with a rigid-body transform\n",
+    "Now, let's use these variants to check how they affect in concatenation with other transforms\n",
+    "\n",
+    "First, we check that, as *NiBabel* represents the data array disregarding the affine, the `.orthoview()` visualization of the *oblique* image shows the same apparent data orientation as for the original file."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 5,
@@ -451,6 +503,13 @@
     "new.orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Create a transform**. We test with a rigid-body transformation with 3 rotations and 3 translations"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 6,
@@ -460,6 +519,14 @@
     "T = nb.affines.from_matvec(nb.eulerangles.euler2mat(x=0.9, y=0.001, z=0.001), [4.0, 2.0, -1.0])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### *NiTransforms*\n",
+    "Let's resample the dataset using *NiTransforms*. This result should be similar with the other libraries."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 7,
@@ -512,6 +579,13 @@
     "moved.orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Store the transform in other formats**. Let's leverage *NiTransforms*' features to store the transforms for ANTs, FSL, and AFNI."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 10,
@@ -544,6 +618,13 @@
     "xfm.to_filename('M.afni', moving=new, fmt='afni')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Testing AFNI"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 24,
@@ -669,6 +750,13 @@
     "moved.orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Testing ANTs/ITK"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 13,
@@ -702,6 +790,13 @@
     "nb.load('moved-itk.nii.gz').orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### Testing FSL"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 14,
@@ -735,6 +830,14 @@
     "nb.load('moved-fsl.nii.gz').orthoview()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Annex: understanding AFNI's deoblique\n",
+    "The code in this section is just a preamble to the following notebook where we explore how AFNI implemented this operation."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 35,
@@ -906,37 +1009,6 @@
     "nb.load('moved-afni2.nii.gz').orthoview()\n",
     "moved.orthoview()"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 31,
-   "metadata": {},
-   "outputs": [
-    {
-     "ename": "FileNotFoundError",
-     "evalue": "No such file or no access: 'moved-RAS.nii.gz'",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[0;31mFileNotFoundError\u001b[0m                         Traceback (most recent call last)",
-      "\u001b[0;32m~/workspace/nibabel/nibabel/loadsave.py\u001b[0m in \u001b[0;36mload\u001b[0;34m(filename, **kwargs)\u001b[0m\n\u001b[1;32m     38\u001b[0m     \u001b[0;32mtry\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 39\u001b[0;31m         \u001b[0mstat_result\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mos\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mstat\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m     40\u001b[0m     \u001b[0;32mexcept\u001b[0m \u001b[0mOSError\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-      "\u001b[0;31mFileNotFoundError\u001b[0m: [Errno 2] No such file or directory: 'moved-RAS.nii.gz'",
-      "\nDuring handling of the above exception, another exception occurred:\n",
-      "\u001b[0;31mFileNotFoundError\u001b[0m                         Traceback (most recent call last)",
-      "\u001b[0;32m<ipython-input-31-56fae86f86fd>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m\u001b[0m\n\u001b[0;32m----> 1\u001b[0;31m \u001b[0mnb\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mload\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'moved-RAS.nii.gz'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0morthoview\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m      2\u001b[0m \u001b[0mnb\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mload\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'moved-affine-oblique-for-T-for.nii.gz'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0morthoview\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m      3\u001b[0m \u001b[0mnb\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mload\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'moved-affine-oblique-for-T-inv.nii.gz'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0morthoview\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-      "\u001b[0;32m~/workspace/nibabel/nibabel/loadsave.py\u001b[0m in \u001b[0;36mload\u001b[0;34m(filename, **kwargs)\u001b[0m\n\u001b[1;32m     39\u001b[0m         \u001b[0mstat_result\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mos\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mstat\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mfilename\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     40\u001b[0m     \u001b[0;32mexcept\u001b[0m \u001b[0mOSError\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 41\u001b[0;31m         \u001b[0;32mraise\u001b[0m \u001b[0mFileNotFoundError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"No such file or no access: '%s'\"\u001b[0m \u001b[0;34m%\u001b[0m \u001b[0mfilename\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m     42\u001b[0m     \u001b[0;32mif\u001b[0m \u001b[0mstat_result\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mst_size\u001b[0m \u001b[0;34m<=\u001b[0m \u001b[0;36m0\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m     43\u001b[0m         \u001b[0;32mraise\u001b[0m \u001b[0mImageFileError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m\"Empty file: '%s'\"\u001b[0m \u001b[0;34m%\u001b[0m \u001b[0mfilename\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
-      "\u001b[0;31mFileNotFoundError\u001b[0m: No such file or no access: 'moved-RAS.nii.gz'"
-     ]
-    }
-   ],
-   "source": []
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {
@@ -955,9 +1027,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.8.5"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

docs/notebooks/02_afni_deoblique.ipynb

@@ -4,7 +4,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## AFNI Deoblique"
+    "## AFNI Deoblique\n",
+    "\n",
+    "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"
    ]
   },
   {
@@ -199,6 +204,13 @@
     "print(np.linalg.inv(np.diag([-1, -1, 1, 1]).dot(R)).T)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Run `3dWarp -deoblique`"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 81,
@@ -286,6 +298,13 @@
     "    return matvec_inv"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Inspecting affines and headers"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 209,
@@ -1020,6 +1039,13 @@
     "print(deob.header.extensions[0].get_content().decode())"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Reverse-engineering matrix compositions of oblique datasets"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 38,
@@ -1183,9 +1209,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.8.5"
   }
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}