Fix MTR example, shuffle figures closer to md files (#13)

* Add readme

* Fix figure

* Add banner

* Fix indice

* Fix missing figs

* Minor

* Shuffle figure notbooks closer to content

* Shuffle figure notbooks closer to content

* Fix missing fig

* Set alternate titles in intro

* Set alternate titles in intro

* Fix example

* Fix example

* Fix example

* Fix example

* Fix example

* Fix example

* Fix example

1 Introduction to qMRI/02-million_dollar.md

@@ -1,5 +1,5 @@
 ---
-title: The million dollar question
+title: Why MRI Isn't Quantitative (Yet)
 subtitle: Pixels have values, then why is MRI not quantitative? 
 date: 2024-10-07
 authors:

1 Introduction to qMRI/03-journey.md

@@ -1,5 +1,5 @@
 ---
-title: A pictorial and historic journey into how MRI works
+title: Origins of MRI - A Visual History
 subtitle: From quantum to macro-scales
 date: 2024-10-07
 authors:

1 Introduction to qMRI/04-encode.md

@@ -1,5 +1,5 @@
 ---
-title: Measuring and encoding the MRI signal
+title: From spin dynamics to images
 date: 2024-10-07
 authors:
   - name: Agah Karakuzu

2 T1 Mapping/2-1 Inversion Recovery/02-IR_SignalModelling.md

@@ -46,15 +46,15 @@ M_z(TI) = C(1-2e^{- \frac{TI}{T_1}})
 
 The simplicity of the signal model described by [](#irEq3), both in its equation and experimental implementation, has made it the most widely used equation to describe the signal evolution in an inversion recovery _T_{sub}`1` mapping experiment. The magnetization curves are plotted in [](#irPlot1) for approximate _T_{sub}`1` values of three different tissues in the brain. Note that in many practical implementations, magnitude-only images are acquired, so the signal measured would be proportional to the absolute value of [](#irEq3).
 
-:::{figure} #fig2p2cell
+:::{figure} #irFig2jn
 :label: irPlot1
 :enumerator: 2.2
 Inversion recovery curves ([](#irEq2)) for three different _T_{sub}`1` values, approximating the main types of tissue in the brain.
 :::
 
 Practically, [](#irEq1) is the better choice for simulating the signal of an [inversion recovery](wiki:Inversion_recovery) experiment, as the TRs are often chosen to be greater than 5_T_{sub}`1` of the tissue-of-interest, which rarely coincides with the longest _T_{sub}`1` present (e.g. TR may be sufficiently long for white matter, but not for CSF which could also be present in the volume). [](#irEq3) also assumes ideal inversion pulses, which is rarely the case due to slice profile effects. [](#irPlot2) displays the [inversion recovery](wiki:Inversion_recovery) signal magnitude (complete relaxation normalized to 1) of an experiment with TR = 5 s and _T_{sub}`1` values ranging between 250 ms to 5 s, calculated using both equations.
 
-:::{figure} #fig2p3cell
+:::{figure} #irFig3jn
 :label: irPlot2
 :enumerator: 2.3
 Signal recovery curves simulated using [](#irEq3) (solid) and [](#irEq1) (dotted) with a TR = 5 s for _T_{sub}`1` values ranging between 0.25 to 5 s.

2 T1 Mapping/2-1 Inversion Recovery/03-IR_DataFitting.md

@@ -29,7 +29,7 @@ S(TI) = a + be^{- \frac{TI}{T_1}}
 where {math}`a` and {math}`b` are complex values. If magnitude-only data is available, a 3-parameter model can be sufficient by taking the absolute value of [Equation 2.4](#irEq4).  While the RD-NLS algorithms are too complex to be presented here (the reader is referred to the paper, (Barral et al. 2010)),  the code for these algorithms [was released open-source](http://www-mrsrl.stanford.edu/~jbarral/t1map.html) along with the original publication, and is also available as a [qMRLab](https://github.com/qMRLab/qMRLab) _T_{sub}`1` mapping model. One important thing to note about [Equation 2.4](#irEq4) is that it is general – no assumption is made about TR – and is thus as robust as [Equation 2.1](#irEq1) as long as all pulse sequence parameters other than TI are kept constant between each measurement. [](#irPlot3) compares simulated data ([Equation 2.1](#irEq1)) using a range of TRs (1.5_T_{sub}`1` to 5_T_{sub}`1`) fitted using either RD-NLS & [Equation 2.4](#irEq4) or a [Levenberg-Marquardt](wiki:Levenberg–Marquardt_algorithm) fit of [Equation 2.2](#irEq2).
 
 
-:::{figure} #fig2p4cell
+:::{figure} #irFig4jn
 :label: irPlot3
 :enumerator: 2.4
 Fitting comparison of simulated data (blue markers) with _T_{sub}`1` = 1 s and TR = 1.5 to 5 s, using fitted using RD-NLS & [Equation 2.4](#irEq4) (green) and [Levenberg-Marquardt](wiki:Levenberg–Marquardt_algorithm) & [Equation 2.2](#irEq2) (orange, long TR approximation).
@@ -39,7 +39,7 @@ Fitting comparison of simulated data (blue markers) with _T_{sub}`1` = 1 s and T
 [](#irPlot4) displays an example brain dataset from an inversion recovery experiment, along with the _T_{sub}`1` map fitted using the RD-NLS technique.
 
 
-:::{figure} #fig2p5cell
+:::{figure} #irFig5jn
 :label: irPlot4
 :enumerator: 2.5
 Example inversion recovery dataset of a healthy adult brain (left). Inversion times used to acquire this magnitude image dataset were 30 ms, 530 ms, 1030 ms, and 1530 ms, and the TR used was 1550 ms. The _T_{sub}`1` map (right) was fitted using a RD-NLS algorithm.

2 T1 Mapping/2-1 Inversion Recovery/04-IR_BenefitsAndPitfalls.md

@@ -22,7 +22,7 @@ The conventional [inversion recovery](wiki:Inversion_recovery) experiment is con
 One important protocol design consideration is to avoid acquiring at inversion times where the signal for _T_{sub}`1` values of the tissue-of-interest is nulled, as the magnitude images at this TI time will be dominated by [Rician](wiki:Rice_distribution) noise which can negatively impact the fit under low SNR circumstances ([](#irPlot5)). Inversion recovery can also often be acquired using commonly available standard pulse sequences available on most MRI scanners by setting up a customized acquisition protocol, and does not require any additional calibration measurements. For an example, please visit the interactive preprint of the ISMRM Reproducible Research Group 2020 Challenge on inversion recovery _T_{sub}`1` mapping {cite:p}`Boudreau2023`. 
 
 
-:::{figure} #fig2p6cell
+:::{figure} #irFig6jn
 :label: irPlot5
 :enumerator: 2.6
 [Monte Carlo](wiki:Monte_Carlo_method) simulations (mean and standard deviation (STD), blue markers) and fitted _T_{sub}`1` values (mean and STD, red and green respectively) generated for a _T_{sub}`1` value of 900 ms and 5 TI values linearly spaced across the TR (ranging from 1 to 5 s). A bump in _T_{sub}`1` STD occurs near TR = 3000 ms, which coincides with the TR where the second TI is located near a null point for this _T_{sub}`1` value.

2 T1 Mapping/2-2 Variable Flip Angle/02-VFA_SignalModelling.md

@@ -26,7 +26,7 @@ M_{z}(\theta_n) = M_0 \frac{1-e^{- \frac{TR}{T_1}}}{1-\text{cos}(\theta_n) e^{-
 
 where _M_{sub}`z` is the longitudinal magnetization, _M_{sub}`0` is the magnetization at thermal equilibrium, TR is the pulse sequence repetition time ([](#vfaFig1)), and {math}`\theta_{n}` is the excitation flip angle. The _M_{sub}`z` curves of different [_T_{sub}`1`](wiki:Spin–lattice_relaxation) values for a range of {math}`\theta_{n}` and TR values are shown in [](#vfaPlot1).
 
-:::{figure} #figvfa2cell
+:::{figure} #vfaFig2jn
 :label: vfaPlot1
 :enumerator: 2.8
 Variable flip angle technique signal curves ([](#vfaEq1)) for three different [_T_{sub}`1`](wiki:Spin–lattice_relaxation) values, approximating the main types of tissue in the brain at 3T.
@@ -45,7 +45,7 @@ From [](#vfaPlot1), it is clearly seen that the flip angle at which the steady-s
 
 The [closed-form solution](wiki:Closed-form_expression) ([](#vfaEq1)) makes several assumptions which in practice may not always hold true if care is not taken. Mainly, it is assumed that the longitudinal magnetization has reached a steady state after a large number of TRs, and that the transverse magnetization is perfectly spoiled at the end of each TR. Bloch simulations – a numerical approach at solving the [Bloch equations](wiki:Bloch_equations) for a set of spins at each time point –  provide a more realistic estimate of the signal if the number of repetition times is small (i.e. a steady-state is not achieved). As can be seen from [](#vfaPlot2), the number of repetitions required to reach a steady state not only depends on [_T_{sub}`1`](wiki:Spin–lattice_relaxation), but also on the flip angle; flip angles near the Ernst angle need more TRs to reach a steady state. Preparation pulses or an outward-in [k-space](wiki:K-space_in_magnetic_resonance_imaging) acquisition pattern are typically sufficient to reach a steady state by the time that the center of [k-space](wiki:K-space_in_magnetic_resonance_imaging) is acquired, which is where most of the image contrast resides.
 
-:::{figure} #figvfa3cell
+:::{figure} #vfaFig3jn
 :label: vfaPlot2
 :enumerator: 2.9
 Example inversion recovery dataset of a healthy adult brain (left). Inversion times used to acquire this magnitude image dataset were 30 ms, 530 ms, 1030 ms, and 1530 ms, and the TR used was 1550 ms. The [_T_{sub}`1`](wiki:Spin–lattice_relaxation) map (right) was fitted using a RD-NLS algorithm.
@@ -57,7 +57,7 @@ Signal curves simulated using Bloch simulations (orange) for a number of repetit
 Sufficient spoiling is likely the most challenging parameter to control for in a VFA experiment. A combination of both gradient spoiling and RF phase spoiling {cite:p}`Handbook2004,Zur1991` are typically recommended ([](#vfaPlot3)). It has also been shown that the use of very strong  gradients, introduces diffusion effects (not considered in [](#vfaPlot3)), further improving the spoiling efficacy in the VFA pulse sequence {cite:p}`Yarnykh2010`.
 
 
-:::{figure} #figvfa4cell
+:::{figure} #vfaFig4jn
 :label: vfaPlot3
 :enumerator: 2.10
 Signal curves estimated using Bloch simulations for three categories of signal spoiling: (1) ideal spoiling (blue), gradient & RF Spoiling (orange), and no spoiling (green). Simulations details: TR = 25 ms, _T_{sub}`1` = 900 ms, T{sub}`e` = 100 ms, TE = 5 ms, 100 spins. For the ideal spoiling case, the transverse magnetization is set to zero at the end of each TR. For the gradient & RF spoiling case, each spin is rotated by different increments of phase (2𝜋 / # of spins) to simulate complete decoherence from gradient spoiling, and the RF phase of the excitation pulse is  {math}`\Phi_{n}=\Phi_{n-1}+n\Phi_{0}=1/2\Phi_{0}\left( n^{2}+n+2 \right)` {cite:p}`Handbook2004` with {math}`\Phi_{0}` = 117° {cite:p}`Zur1991` after each TR.

2 T1 Mapping/2-2 Variable Flip Angle/03-VFA_DataFitting.md

@@ -46,7 +46,7 @@ T_1 = - \frac{TR}{ \text{ln}(slope)}
 
 If data were acquired using only two flip angles – a very common VFA acquisition protocol – then the slope can be calculated using the elementary slope equation. [](#vfaPlot4) displays both Equations [](#vfaEq1) and [](#vfaEq4) plotted for a noisy dataset.
 
-:::{figure} #figvfa5cell
+:::{figure} #vfaFig5jn
 :label: vfaPlot4
 :enumerator: 2.11
 Mean and standard deviation of the VFA signal plotted using the nonlinear form ([](#vfaEq1) – blue) and linear form ([](#vfaEq4) – red). Monte Carlo simulation details: SNR = 25, N = 1000. VFA simulation details: TR = 25 ms, _T_{sub}`1` = 900 ms.
@@ -68,15 +68,15 @@ Accurate knowledge of the flip angle values is very important to produce accurat
 
 _B_{sub}`1` in this context is normalized, meaning that it is unitless and has a value of 1 in voxels where the RF field has the expected amplitude (i.e. where the nominal flip angle is the actual flip angle). [](#vfaPlot5) displays fitted VFA [_T_{sub}`1`](wiki:Spin–lattice_relaxation) values from a [Monte Carlo](wiki:Monte_Carlo_method) dataset simulated using biased flip angle values, and fitted without/with _B_{sub}`1` correction.
 
-:::{figure} #figvfa6cell
+:::{figure} #vfaFig6jn
 :label: vfaPlot5
 :enumerator: 2.12
 Mean and standard deviations of fitted VFA [_T_{sub}`1`](wiki:Spin–lattice_relaxation) values for a set of [Monte Carlo](wiki:Monte_Carlo_method) simulations (SNR = 100, N = 1000), simulated using a wide range of biased flip angles and fitted without (blue) or with (red) _B_{sub}`1` correction. Simulation parameters: TR = 25 ms, _T_{sub}`1` = 900 ms, {math}`\theta_{nominal}` = 6° and 32° (optimized values for this TR/_T_{sub}`1` combination). Notice how even after _B_{sub}`1` correction, fitted [_T_{sub}`1`](wiki:Spin–lattice_relaxation) values at _B_{sub}`1` values far from the nominal case (_B_{sub}`1` = 1) exhibit larger variance, as the actual flip angles of the simulated signal deviate from the optimal values for this TR/_T_{sub}`1` (Deoni et al. 2003).
 :::
 
 [](#vfaPlot6) displays an example VFA dataset and a _B_{sub}`1` map in a healthy brain, along with the _T_{sub}`1` map estimated using a linear fit (Equations [](#vfaEq4) and [](#vfaEq5)).
 
-:::{figure} #figvfa7cell
+:::{figure} #vfaFig7jn
 :label: vfaPlot6
 :enumerator: 2.13
 Example variable flip angle dataset and _B_{sub}`1` map of a healthy adult brain (left). The relevant VFA protocol parameters used were: TR = 15 ms,  {math}`\theta_{nominal}` = 3° and 20°. The _T_{sub}`1` map (right) was fitted using a linear regression (Equations [](#vfaEq4) and [](#vfaEq5)).