DOC: Add post-hoc adjustment section

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",
     ],

docs/src/adjust_sequences.md

+# [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,
+]
+```
+

docs/src/api.md

@@ -45,13 +45,6 @@ Modules = [
     MRIBuilder.Parts.EPIReadouts,
 ]
 ```
-## Post-hoc adjustments
-```@autodocs
-Modules = [
-    MRIBuilder.PostHoc,
-]
-```
-
 ## Sequence I/O
 ```@autodocs
 Modules = [

docs/src/defining_sequence.md

@@ -103,7 +103,7 @@ Modules = [
 ```
 
 
-## Pathways
+## Pathways API
 ```@autodocs
 Modules = [
     MRIBuilder.Pathways,