Skip to content

Commit

Permalink
enh: update notebook
Browse files Browse the repository at this point in the history
  • Loading branch information
@oesteban
oesteban committed Apr 26, 2024
1 parent 2307c7f commit 77da183
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 5 deletions.
31 changes: 29 additions & 2 deletions docs/notebook/01-intro.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
"id": "630e4332",
"metadata": {},
"source": [
"# The problem of head-motion in dMRI"
Expand All @@ -10,6 +11,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "1ce9af2e",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -26,6 +28,7 @@
},
{
"cell_type": "markdown",
"id": "8fb8ee58",
"metadata": {},
"source": [
"A recurring problem for any MRI acquisition is that image reconstruction and modeling are extremely sensitive to very small changes in the position of the imaged object.\n",
Expand All @@ -38,6 +41,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "cb07fe37",
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -46,6 +50,7 @@
},
{
"cell_type": "markdown",
"id": "2076c0f1",
"metadata": {},
"source": [
"## Dimensions of the head-motion problem\n",
Expand Down Expand Up @@ -102,6 +107,8 @@
"- Memory fingerprint: DWIs can be large, and storing them in memory (and subsequent derivatives thereof) can be cumbersome, or even prohibitive.\n",
"- Parallelism: simulation and registration are CPU-intensive processes - for the runtime to be in a manageable scale, we'll need to leverage parallelism.\n",
"\n",
"![eddymotion](https://raw.githubusercontent.com/nipreps/eddymotion/507fc9bab86696d5330fd6a86c3870968243aea8/docs/_static/eddymotion-flowchart.svg)\n",
"\n",
"**Sketch out an API (Application Programming Interface)**: Plan how the new software will expose the implementation downstream.\n",
"Assuming our DWI data is encapsulated in an object (holding not just the data array, but also metadata such as the gradient table)\n",
"pointed at by the variable `data`, and assuming we have a list of rigid-body transform matrices to initialize the algorithm (`mats`),\n",
Expand All @@ -117,15 +124,35 @@
"corrected = estimator.predict(data)\n",
"```"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c133e5f7-927d-468c-822a-eb4dfd2c6635",
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.9"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
}
50 changes: 47 additions & 3 deletions docs/notebook/02-data.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
"cells": [
{
"cell_type": "markdown",
"id": "f5123198",
"metadata": {},
"source": [
"# Introduction to dMRI data"
Expand All @@ -10,6 +11,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "89569811",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -26,6 +28,7 @@
},
{
"cell_type": "markdown",
"id": "74fe239e",
"metadata": {},
"source": [
"Diffusion imaging probes the random, microscopic movement of water molecules by using MRI sequences that are sensitive to the geometry and environmental organization surrounding these protons.\n",
Expand All @@ -37,6 +40,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "a1098cf6",
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -45,6 +49,7 @@
},
{
"cell_type": "markdown",
"id": "62545c69",
"metadata": {},
"source": [
"*Sourced from Dr. A. Rokem, DIPY Workshop 2021*\n",
Expand Down Expand Up @@ -77,6 +82,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "0be2bc8e",
"metadata": {},
"outputs": [],
"source": [
Expand Down Expand Up @@ -114,6 +120,7 @@
},
{
"cell_type": "markdown",
"id": "5d0d7f99",
"metadata": {},
"source": [
"This code implements several *attributes* as well as a *behavior* - the `__len__` *method*.\n",
Expand All @@ -125,6 +132,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "875e9e63",
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -140,6 +148,7 @@
},
{
"cell_type": "markdown",
"id": "9cbdce98",
"metadata": {},
"source": [
"The output of this `print()` statement is telling us that this (simulated) dataset has 64 diffusion-weighted samples.\n",
Expand All @@ -156,11 +165,12 @@
{
"cell_type": "code",
"execution_count": null,
"id": "0760d003",
"metadata": {},
"outputs": [],
"source": [
"# import the class from the library\n",
"from eddymotion.dmri import DWI\n",
"from eddymotion.data.dmri import DWI\n",
"\n",
"# load the sample file\n",
"dmri_dataset = DWI.from_filename(\"../../data/dwi.h5\")\n",
Expand All @@ -169,6 +179,7 @@
},
{
"cell_type": "markdown",
"id": "e400e285",
"metadata": {},
"source": [
"In this case, the dataset is reporting to have 102 diffusion-weighted samples.\n",
Expand All @@ -180,6 +191,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "4eb3a412",
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -188,6 +200,7 @@
},
{
"cell_type": "markdown",
"id": "b3d42b3a",
"metadata": {},
"source": [
"We'll go over some of the components of `dmri_dataset` through this lesson.\n",
Expand All @@ -207,6 +220,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "11ae0396",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -219,6 +233,7 @@
},
{
"cell_type": "markdown",
"id": "6ba5b5fb",
"metadata": {},
"source": [
"When calling `plot_mosaic()` without any arguments, the *b=0* reference is plotted.\n",
Expand All @@ -237,6 +252,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "de6b4724",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -248,6 +264,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "1bde9b81",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -258,6 +275,7 @@
},
{
"cell_type": "markdown",
"id": "abe42cf8",
"metadata": {},
"source": [
"Diffusion that exhibits directionality in the same direction as the gradient results in a loss of signal.\n",
Expand All @@ -280,6 +298,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "501c5de7",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -290,6 +309,7 @@
},
{
"cell_type": "markdown",
"id": "7783f6f2",
"metadata": {},
"source": [
"We get a $4\\times102$ -- three spatial coordinates ($b_x$, $b_y$, $b_z$) of the unit-norm \"*b-vector*\", plus the gradient sensitization magnitude (the \"*b-value*\"), with a total of 102 different orientations for the case at hand.\n",
Expand All @@ -305,6 +325,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "ca843407",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -315,6 +336,7 @@
},
{
"cell_type": "markdown",
"id": "92e63a6c",
"metadata": {},
"source": [
"Later, we'll refer to this array as the gradient table.\n",
Expand All @@ -337,12 +359,14 @@
{
"cell_type": "code",
"execution_count": null,
"id": "85677774",
"metadata": {},
"outputs": [],
"source": []
},
{
"cell_type": "markdown",
"id": "a4a43cdc",
"metadata": {},
"source": [
"We've projected all of the gradient directions onto the surface of a sphere, with each unique gradient strength colour-coded.\n",
Expand All @@ -359,6 +383,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "2023e87a",
"metadata": {},
"outputs": [],
"source": [
Expand Down Expand Up @@ -413,6 +438,7 @@
},
{
"cell_type": "markdown",
"id": "99e429f3",
"metadata": {},
"source": [
"This function is contained in the `DWI` class shown earlier and will allow us to easily partition the dataset as follows:"
Expand All @@ -421,6 +447,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "1d4df79a",
"metadata": {},
"outputs": [],
"source": [
Expand All @@ -432,6 +459,7 @@
},
{
"cell_type": "markdown",
"id": "4b9a33f1",
"metadata": {},
"source": [
"`data_train` is a tuple containing all diffusion-weighted volumes and the corresponding gradient table, excluding the left-out, which is stored in `data_test` (the 11<sup>th</sup> gradient indexed by `10`, in this example).\n",
Expand All @@ -447,6 +475,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "c3fe53a2",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -457,6 +486,7 @@
},
{
"cell_type": "markdown",
"id": "4b6a79e7",
"metadata": {},
"source": [
"**Exercise**\n",
Expand All @@ -469,6 +499,7 @@
{
"cell_type": "code",
"execution_count": null,
"id": "e4e4a23d",
"metadata": {
"tags": [
"hide-cell"
Expand All @@ -479,6 +510,7 @@
},
{
"cell_type": "markdown",
"id": "a6937911",
"metadata": {},
"source": [
"## Next steps: diffusion modeling\n",
Expand All @@ -489,11 +521,23 @@
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"display_name": "Python 3 (ipykernel)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.9"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
}
1 change: 1 addition & 0 deletions requirements.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ git+https://github.com/nipreps/eddymotion.git@main
ghp-import
jupyter-book
jupytext
jupyterlab
matplotlib
nibabel
nilearn
Expand Down

0 comments on commit 77da183

Please sign in to comment.