From 5cba12e1e47469be25b2137f167ae4cb62fac1cf Mon Sep 17 00:00:00 2001
From: Michiel Cottaar <MichielCottaar@protonmail.com>
Date: Wed, 15 May 2024 17:32:19 +0100
Subject: [PATCH] DOC: Add post-hoc adjustment section
---
docs/make.jl | 2 ++
docs/src/adjust_sequences.md | 31 +++++++++++++++++++++++++++++++
docs/src/api.md | 7 -------
docs/src/defining_sequence.md | 2 +-
4 files changed, 34 insertions(+), 8 deletions(-)
create mode 100644 docs/src/adjust_sequences.md
diff --git a/docs/make.jl b/docs/make.jl
index 2011745..7eaff64 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -20,6 +20,8 @@ makedocs(;
"Home" => "index.md",
"Optimisation" => "sequence_optimisation.md",
"Implemented sequences" => "implemented_sequences.md",
+ "Defining sequences" => "defining_sequence.md",
+ "Post-hoc adjustments" => "adjust_sequences.md",
"Scanners" => "scanners.md",
"Internal API" => "api.md",
],
diff --git a/docs/src/adjust_sequences.md b/docs/src/adjust_sequences.md
new file mode 100644
index 0000000..88c57aa
--- /dev/null
+++ b/docs/src/adjust_sequences.md
@@ -0,0 +1,31 @@
+# [Post-hoc adjustment of sequences](@id adjust_sequences)
+Typically a sequence is repeated for multiple [`repetition_time`](@ref) ([`TR`](@ref)) to allow the acquisition of multiple k-space lines, slice selection, or other sequence parameters (e.g., varying diffusion-weighting parameters for [`DiffusionSpinEcho`](@ref)).
+MRIBuilder supports this by allowing the creation of a longer sequence out of multiple repeats of a base sequence with some minor alterations.
+
+To support post-hoc alterations, each RF pulse or gradient waveform in the sequence can be given a label.
+Some commonly-used labels in MRIBuilder are:
+- `:diffusion`: used for diffusion-weighted gradients produced by [`dwi_gradients`](@ref).
+- `:FOV`: used for gradients that should align with the field-of-view (slice-select gradients in [`excitation_pulse`](@ref) or [`refocus_pulse`](@ref) and readout gradients in [`readout_event`](@ref)).
+
+Post-hoc alterations can be applied to gradients or RF pulses with a specific labels (or to all gradients/RF pulses) using [`adjust`](@ref).
+Some example usages are:
+- Reduce the RF pulse amplitude by 20% (e.g., due to transmit bias field): `adjust(sequence, pulse=(scale=0.8, ))`
+- Repeat sequence 2 times with different diffusion-weighted gradient orientations (x- and y-direction) and gradient strength reduced by 30%: `adjust(sequence, diffusion=(orientation=[[1., 0., 0], [0., 1., 0.]], scale=0.7))`
+- Rotate the field of view by 45 degrees around the y-axis:
+```julia
+using Rotations
+rotation = Rotations.AngleAxis(deg2rad(45), 0., 1., 0.)
+adjust(sequence, FOV=(rotation=rotation, ))
+```
+When repeating the same sequence, a spoiler gradient and/or dead time can be added in between each pair of repeats by supplying the appropriate keywords to the `merge` parameter in [`adjust`](@ref) (e.g., `merge=(wait_time=10., )`). These parameters are described in more detail in [`merge_sequences`](@ref).
+
+## Post-hoc adjustments API
+```@meta
+CollapsedDocStrings = true
+```
+```@autodocs
+Modules = [
+ MRIBuilder.PostHoc,
+]
+```
+
diff --git a/docs/src/api.md b/docs/src/api.md
index b74d3ca..e8c124c 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -45,13 +45,6 @@ Modules = [
MRIBuilder.Parts.EPIReadouts,
]
```
-## Post-hoc adjustments
-```@autodocs
-Modules = [
- MRIBuilder.PostHoc,
-]
-```
-
## Sequence I/O
```@autodocs
Modules = [
diff --git a/docs/src/defining_sequence.md b/docs/src/defining_sequence.md
index 05a73cd..1244331 100644
--- a/docs/src/defining_sequence.md
+++ b/docs/src/defining_sequence.md
@@ -103,7 +103,7 @@ Modules = [
```
-## Pathways
+## Pathways API
```@autodocs
Modules = [
MRIBuilder.Pathways,
--
GitLab