Skip to content

Commit

Permalink
Merge pull request #222 from Bradley-Karat/introduction
Browse files Browse the repository at this point in the history 
DOC: Update introduction and preprocessing lessons
  • Loading branch information
@jhlegarreta
jhlegarreta authored Nov 12, 2023
2 parents 09182e5 + b2e30d0 commit bfa5595
Show file tree
Hide file tree
Showing 7 changed files with 165 additions and 124 deletions.
120 changes: 68 additions & 52 deletions _episodes/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,32 +23,48 @@ math: true
## Diffusion Weighted Imaging (DWI)

Diffusion MRI is a popular technique to study the brain's white matter. To do
so, sequences sensitive to random, microscropic motion of water protons are
applied. The diffusion within biological structures, such as the brain, are
often restricted due to barriers (e.g. cell membranes), resulting in a
preferred direction of diffusion (anisotropy). A typical diffusion MRI scan
will acquire multiple volumes that are sensitive to a particular diffusion
direction and result in diffusion-weighted images (DWI). Diffusion that
exhibits directionality in the same direction result in an attenuated signal.
With further processing (to be discussed later in the lesson), the acquired
images can provide measurements which are related to the microscopic changes
and estimate white matter trajectories. Images with no diffusion weighting are
also acquired as part of the acquisition protocol.

![Diffusion along X, Y, and Z directions]({{ relative_root_path }}/fig/introduction/DiffusionDirections.png) \
Diffusion along X, Y, and Z directions
so, MRI sequences which are sensitive to the random, microscropic motion (i.e.
diffusion) of water protons are used. The diffusion of water within biological
structures, such as the brain, are often restricted due to barriers (e.g. cell
membranes), resulting in a preferred direction of diffusion (anisotropy). A
typical diffusion MRI scan will acquire multiple volumes with varying magnetic
fields (i.e. diffusion gradients) which are sensitive to diffusion along a
particular direction and result in diffusion-weighted images (DWI). Water
diffusion that is occurring along the same direction as the diffusion gradient
results in an attenuated signal. Images with no diffusion weighting (i.e. no
diffusion gradient) are also acquired as part of the acquisition protocol. With
further processing (to be discussed later in the lesson), the acquired images
can provide measurements which are related to the microscopic properties of
brain tissue. DWI has been used extensively to diagnose stroke, assess white
matter damage in many different kinds of diseases, provide insights into the
white matter connectivity, and much more!

![fiber_configurations]
({{ relative_root_path }}/fig/introduction/diffusion_direction_new.png)
\Diffusion along X, Y, and Z directions. The signal in the left/right oriented
corpus callosum is lowest when measured along X, while the signal in the
inferior/superior oriented corticospinal tract is lowest when measured along Z.

## b-values & b-vectors

In addition to the acquired diffusion images, two files are collected as part
of the diffusion dataset. These files correspond to the gradient amplitude
(b-values) and directions (b-vectors) of the diffusion measurement and are
named with the extensions <code>.bval</code> and <code>.bvec</code>
respectively. The b-value is the diffusion-sensitizing factor, and reflects the
timing & strength of the gradients used to acquire the diffusion-weighted
images. The b-vector corresponds to the direction of the diffusion sensitivity.
Together these two files define the diffusion MRI measurement as a set of
gradient directions and corresponding amplitudes.
of the diffusion dataset, known as the b-vectors and b-values. The b-value
(file suffix <code>.bval</code>) is the diffusion-sensitizing factor, and
reflects the timing and strength of the diffusion gradients. A larger b-value
means our DWI signal will be more sensitive to the diffusion of water.
The b-vector (file suffix <code>.bvec</code>) corresponds to the direction
with which diffusion was measured. Together, these two files define the
diffusion MRI measurement as a set of gradient directions and corresponding
amplitudes, and are necessary to calculate useful measures of the microscopic
properties. The DWI acquisition process is thus:
1. Pick a direction to measure diffusion along (i.e. pick the diffusion gradient
direction). This is recorded in the <code>.bvec</code> file.
1. Pick a strength of the magnetic gradient. This is recorded in the
<code>.bval</code> file.
1. Acquire the MRI with these settings to examine water diffusion along the
chosen direction. This is the DWI volume.
1. Thus, for every DWI volume we have an associated b-value and b-vector which
tells us how we measured the diffusion.

## Dataset

Expand Down Expand Up @@ -128,12 +144,13 @@ tree '../data/ds000221'

## Querying a BIDS Dataset

[PyBIDS](https://bids-standard.github.io/pybids/) is a Python package for
[pybids](https://bids-standard.github.io/pybids/) is a Python package for
querying, summarizing and manipulating the BIDS folder structure. We will make
use of `PyBIDS` to query the necessary files.
use of `pybids` to query the necessary files.

Let's first pull the metadata from its associated JSON file using the
<code>get_metadata()</code> function for the first run.
Let's first pull the metadata from its associated JSON file
(dictionary-like data storage) using the <code>get_metadata()</code>
function for the first run.

~~~
from bids.layout import BIDSLayout
Expand Down Expand Up @@ -267,15 +284,36 @@ gtab = gradient_table(gt_bvals, gt_bvecs)
~~~
{: .language-python}

We will need this gradient table later on to process our data and generate
diffusion tensor images (DTI)!
We will need this gradient table later on to process and model our data!

There is also a built-in function for gradient tables, <code>b0s_mask</code>
that can be used to separate diffusion weighted measurements from non-diffusion
weighted measurements ($b = 0 s/mm^2$, commonly referred to as the B0 volume or
image). We will extract the vector corresponding to diffusion weighted
measurements!
image). It is important to know where our diffusion weighted free measurements
are as we need them for registration in our preprocessing (our next notebook).
<code>gtab.b0s_mask</code> shows that this is our first volume of our
dataset.

~~~
gtab.b0s_mask
~~~
{: .language-python}

~~~
array([ True, False, False, False, False, False, False, False, False,
False, False, True, False, False, False, False, False, False,
False, False, False, False, True, False, False, False, False,
False, False, False, False, False, False, True, False, False,
False, False, False, False, False, False, False, False, True,
False, False, False, False, False, False, False, False, False,
False, True, False, False, False, False, False, False, False,
False, False, False, True])
~~~
{: .output}

We will also extract the vector corresponding to only diffusion weighted
measurements (or equivalently, return everything that is not a $b = 0 s/mm^2$)!

~~~
gtab.bvecs[~gtab.b0s_mask]
~~~
Expand Down Expand Up @@ -345,28 +383,6 @@ array([[-2.51881e-02, -3.72268e-01, 9.27783e-01],
~~~
{: .output}

It is also important to know where our diffusion weighting free measurements
are as we need them for registration in our preprocessing, (our next notebook).
<code>gtab.b0s_mask</code> shows that this is our first volume of our
dataset.

~~~
gtab.b0s_mask
~~~
{: .language-python}

~~~
array([ True, False, False, False, False, False, False, False, False,
False, False, True, False, False, False, False, False, False,
False, False, False, False, True, False, False, False, False,
False, False, False, False, False, False, True, False, False,
False, False, False, False, False, False, False, False, True,
False, False, False, False, False, False, False, False, False,
False, True, False, False, False, False, False, False, False,
False, False, False, True])
~~~
{: .output}

In the next few notebooks, we will talk more about preprocessing the diffusion
weighted images, reconstructing the diffusion tensor model, and reconstruction
axonal trajectories via tractography.
Expand Down
37 changes: 21 additions & 16 deletions _episodes/preprocessing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,20 @@ math: true

## Diffusion Preprocessing

Diffusion preprocessing typically comprises of a series of steps, which may
vary depending on how the data is acquired. Some consensus has been reached for
certain preprocessing steps, while others are still up for debate. The lesson
will primarily focus on the preprocessing steps where consensus has been
reached. Preprocessing is performed using a few well-known software packages
(e.g. `FSL`, `ANTs`). For the purposes of these lessons, preprocessing steps
requiring these software packages has already been performed for the dataset
<code>ds000221</code> and the commands required for each step will be provided.
This dataset contains single shell diffusion data with 7 $b = 0 s/mm^2$ volumes
(non-diffusion weighted) and 60 $b = 1000 s/mm^2$ volumes. In addition, field
maps (found in the <code>fmap</code> directory are acquired with opposite
phase-encoding directions).
Diffusion MRI data does not typically come off the scanner ready to be analyzed,
and there can be many things that might need to be corrected before analysis.
Diffusion preprocessing typically comprises of a series of steps to perform the
necessary corrections to the data. These steps may vary depending on how the data
is acquired. Some consensus has been reached for certain preprocessing steps,
while others are still up for debate. The lesson will primarily focus on the
preprocessing steps where consensus has been reached. Preprocessing is performed
using a few well-known software packages (e.g. [FSL](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki), [ANTs](https://github.com/ANTsX/ANTs). For the purposes
of these lessons, preprocessing steps requiring these software packages has already
been performed for the dataset <code>ds000221</code> and the commands required for
each step will be provided. This dataset contains single shell diffusion data with
7 $b = 0 s/mm^2$ volumes (non-diffusion weighted) and 60 $b = 1000 s/mm^2$ volumes.
In addition, field maps (found in the <code>fmap</code> directory are acquired
with opposite phase-encoding directions).

To illustrate what the preprocessing step may look like, here is an example
preprocessing workflow from QSIPrep (Cieslak _et al_, 2020):
Expand All @@ -50,9 +52,9 @@ lesson.
### Brainmasking

The first step to the preprocessing workflow is to create an appropriate
brainmask from the diffusion data! Start, by first importing the necessary
modules. and reading the diffusion data! We will also grab the anatomical T1w
image to use later on, as well as the second inversion from the anatomical
brainmask from the diffusion data! Start by first importing the necessary modules and
reading the diffusion data along with the coordinate system (the affine)! We will also grab
the anatomical T1w image to use later on, as well as the second inversion from the anatomical
acquisition for brainmasking purposes.

~~~
Expand Down Expand Up @@ -112,7 +114,7 @@ nib.save(img, os.path.join(out_dir, f"sub-{subj}_ses-01_brainmask.nii.gz"))

Diffusion images, typically acquired using spin-echo echo planar imaging (EPI),
are sensitive to non-zero off-resonance fields. One source of these fields is
from the susceptibilitiy distribution of the subjects head, otherwise known as
from the susceptibility distribution of the subjects head, otherwise known as
susceptibility-induced off-resonance field. This field is approximately
constant for all acquired diffusion images. As such, for a set of diffusion
volumes, the susceptibility-induced field will be consistent throughout. This
Expand All @@ -126,6 +128,9 @@ differs. Typically, this is done using two acquisitions acquired with opposite
phase-encoding directions, which results in the same field creating distortions
in opposing directions.

![blips]({{ relative_root_path }}/fig/preprocessing/blip_up_blip_down.png)
Opposite phase-encodings from two DWI

Here, we will make use of the two opposite phase-encoded acquisitions found in
the <code>fmap</code> directory of each subject. These are acquired with a
diffusion weighting of $b = 0 s/mm^2$. Alternatively, if these are not
Expand Down
97 changes: 56 additions & 41 deletions code/introduction.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,21 +11,27 @@
"\n",
"## Diffusion Weighted Imaging (DWI)\n",
"\n",
"Diffusion MRI is a popular technique to study the brain's white matter. To do\n",
"so, sequences sensitive to random, microscropic motion of water protons are\n",
"applied. The diffusion within biological structures, such as the brain, are\n",
"often restricted due to barriers (e.g. cell membranes), resulting in a\n",
"preferred direction of diffusion (anisotropy). A typical diffusion MRI scan\n",
"will acquire multiple volumes that are sensitive to a particular diffusion\n",
"direction and result in diffusion-weighted images (DWI). Diffusion that\n",
"exhibits directionality in the same direction result in an attenuated signal.\n",
"With further processing (to be discussed later in the lesson), the acquired\n",
"images can provide measurements which are related to the microscopic changes\n",
"and estimate white matter trajectories. Images with no diffusion weighting are\n",
"also acquired as part of the acquisition protocol.\n",
"Diffusion MRI is a popular technique to study the brain's white matter. To do so, \n",
"MRI sequences which are sensitive to the random, microscropic motion \n",
"(i.e. diffusion) of water protons are used. The diffusion of water within \n",
"biological structures, such as the brain, are often restricted due to barriers \n",
"(e.g. cell membranes), resulting in a preferred direction of diffusion \n",
"(anisotropy). A typical diffusion MRI scan will acquire multiple volumes with \n",
"varying magnetic fields (i.e. diffusion gradients) which are sensitive to \n",
"diffusion along a particular direction and result in diffusion-weighted images \n",
"(DWI). Water diffusion that is occurring along the same direction as the \n",
"diffusion gradient results in an attenuated signal. Images with no diffusion \n",
"weighting (i.e. no diffusion gradient) are also acquired as part of the \n",
"acquisition protocol. With further processing (to be discussed later in the \n",
"lesson), the acquired images can provide measurements which are related to the \n",
"microscopic properties of brain tissue. DWI has been used extensively to \n",
"diagnose stroke, assess white matter damage in many different kinds of diseases, \n",
"provide insights into the white matter connectivity, and much more!\n",
"\n",
"![fiber_configurations](../fig/introduction/DiffusionDirections.png) \\\n",
"Diffusion along X, Y, and Z directions"
"![fiber_configurations](../fig/introduction/diffusion_direction_new.png) \\\n",
"Diffusion along X, Y, and Z directions. The signal in the left/right oriented \n",
"corpus callosum is lowest when measured along X, while the signal in the \n",
"inferior/superior oriented corticospinal tract is lowest when measured along Z."
]
},
{
Expand All @@ -34,15 +40,24 @@
"source": [
"## b-values & b-vectors\n",
"\n",
"In addition to the acquired diffusion images, two files are collected as part\n",
"of the diffusion dataset. These files correspond to the gradient amplitude\n",
"(b-values) and directions (b-vectors) of the diffusion measurement and are\n",
"named with the extensiosn `.bval` and `.bvec` respectively. The b-value is the\n",
"diffusion-sensitizing factor, and reflects the timing & strength of the\n",
"gradients used to acquire the diffusion-weighted images. The b-vector\n",
"corresponds to the direction of the diffusion sensitivity. Together these two\n",
"files define the diffusion MRI measurement as a set of gradient directions and\n",
"corresponding amplitudes."
"In addition to the acquired diffusion images, two files are collected as part \n",
"of the diffusion dataset, known as the b-vectors and b-values. The b-value \n",
"(file suffix `.bval`) is the diffusion-sensitizing factor, and reflects the \n",
"timing and strength of the diffusion gradients. A larger b-value means our \n",
"DWI signal will be more sensitive to the diffusion of water. The b-vector \n",
"(file suffix `.bvec`) corresponds to the direction with which diffusion was \n",
"measured. Together, these two files define the diffusion MRI measurement as a \n",
"set of gradient directions and corresponding amplitudes, and are necessary to \n",
"calculate useful measures of the microscopic properties. The DWI acquisition \n",
"process is thus:\n",
"\n",
"1. Pick a direction to measure diffusion along (i.e. pick the diffusion gradient \n",
" direction). This is recorded in the .bvec file.\n",
"2. Pick a strength of the magnetic gradient. This is recorded in the .bval file.\n",
"3. Acquire the MRI with these settings to examine water diffusion along the \n",
" chosen direction. This is the DWI volume.\n",
"4. Thus, for every DWI volume we have an associated b-value and b-vector which \n",
" tells us how we measured the diffusion."
]
},
{
Expand Down Expand Up @@ -322,14 +337,15 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"We will need this gradient table later on to process our data and generate\n",
"diffusion tensor images (DTI)!\n",
"We will need this gradient table later on to process and model our data!\n",
"\n",
"There is also a built-in function for gradient tables, `b0s_mask` that can be\n",
"used to separate difussion weighted measurements from non-diffusion weighted\n",
"measurements ($b = 0 s/mm^2$, commonly referred to as the B0 volume or image).\n",
"Try to extract the vector corresponding to diffusion weighted measurements in\n",
"the following cell!"
"There is also a built-in function for gradient tables, b0s_mask\n",
"that can be used to separate diffusion weighted measurements from non-diffusion\n",
"weighted measurements ($b = 0 s/mm^2$, commonly referred to as the B0 volume or\n",
"image). It is important to know where our diffusion weighted free measurements\n",
"are as we need them for registration in our preprocessing (our next notebook).\n",
"`gtab.b0s_mask` shows that this is our first volume of our\n",
"dataset."
]
},
{
Expand All @@ -338,16 +354,15 @@
"metadata": {},
"outputs": [],
"source": [
"gtab.bvecs[~gtab.b0s_mask]"
"gtab.b0s_mask"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It is also important to know where our diffusion weighting free measurements\n",
"are as we need them for registration in our preprocessing, (our next notebook).\n",
"`gtab.b0s_mask` shows that this is the first volume of our dataset."
"We will also extract the vector corresponding to only diffusion weighted \n",
"measurements (or equivalently, return everything that is not a $b = 0 s/mm^2$)!"
]
},
{
Expand All @@ -356,7 +371,7 @@
"metadata": {},
"outputs": [],
"source": [
"gtab.b0s_mask"
"gtab.bvecs[~gtab.b0s_mask]"
]
},
{
Expand All @@ -382,13 +397,13 @@
{
"cell_type": "code",
"execution_count": null,
"source": [
"dwi_data = layout.get(suffix='dwi', extension='.nii.gz', return_type='file')"
],
"outputs": [],
"metadata": {
"solution2": "hidden"
}
},
"outputs": [],
"source": [
"dwi_data = layout.get(suffix='dwi', extension='.nii.gz', return_type='file')"
]
},
{
"cell_type": "code",
Expand Down Expand Up @@ -424,4 +439,4 @@
},
"nbformat": 4,
"nbformat_minor": 4
}
}
Loading

0 comments on commit bfa5595

Please sign in to comment.