enh: update acquisition materials

docs/animal-qc/acquisition.md

@@ -21,15 +21,16 @@ Those with Bruker scanners may also have a maintenance package which includes te
 for quality assurance.
 ### Coils
 Some volume coils require manual tuning.
-For scanners from out-of-business manufacturers, "homemade" coils are more common
-and less standardised.
+For scanners from out-of-business manufacturers, "homemade" coils are more common.
+These coils use known standards in day-to-day scanning, so are possibly more standardised in terms
+of replicability, but may be less standardised across sites.
 Cryocoils are increasingly available but not yet ubiquitous.
 ### Physiological monitoring
 While the requirements for accurate physiological monitoring is explained in more
 detail below, there are many pieces of hardware that can be discussed.
 This minimally includes rectal thermometers and respiration balloons, but can also
 include pulse oximeters and/or invasive blood pressure monitoring.
-### Other hardware_
+### Other hardware
 Cradles, bite bars, ear bars, pillows can be provided by the scanner manufacturer or
 "homemade".
 These facilitate support of the animal in the scanner and reduce movement.
@@ -104,13 +105,14 @@ Compound | Administration | Benefits | Costs
 Isoflurane | inhalation | <li> non-invasive administration</li><li>Short recovery</li>|<li>Uncouples BOLD response</li><li>Dangerous cumulative effects</li>
 (Dex)meditomidine | infusion | <li> preserves BOLD response </li> | <li>requires Atipamezole for speedy recovery</li>
 Alpha-Chloralose | infusion |<li> preserves BOLD response </li> | <li> requires cannulation</li><li>Difficult recovery</li>
-Ketamine | infusion | |
+Ketamine | infusion | <li>established anaesthetic<li> <li> single administration has long effects</li> <li>easily reversible</li>  | <li>confound with BOLD response</li>
+Halothane | inhalation | <li> non-invasive administration </li> <li>preserves BOLD response</li> | <li>toxic</li> <li>increasingly hard to acquire</li>
 
 ### Respiration
 Respiration rate and the pattern of inhalation is impacted by the choice of
 anaesthesia or sedative.
 Often anaesthetic procedures prescribe a respiration rate to standardise across
-animals, rather than a rate of anaesthetic delivery.
+animals, with a wider range of rates for anaesthetic delivery.
 
 ### Thermal homeostasis
 Small animals, particularly mice, find it difficult to regulate their body

docs/animal-qc/acquisition_examples.md

@@ -29,7 +29,7 @@ You have your hypotheses.
 You've planned your study design.
 It's time to acquire your data.
 
-But first, it's important to develop a **standard operating procedure** for your acquisition.
+But first, it's important to develop a *standard operating procedure* for your acquisition.
 This will not only make sure that you run things consistently, but also it will minimise experimenter effects 
 in your experiments by having agreed upon, well-defined criteria for the success of your acquisition.
 
@@ -44,8 +44,7 @@ Let's start off with an easy one: below is a T2-weighted structural image.
 import nanslice.jupyter as ns
 %matplotlib widget
 
-fname = './assets/example-1_desc-orig_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+# ns.three_plane('./assets/example-1_desc-orig_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 ```{admonition} What do you think the problem was?
@@ -58,24 +57,29 @@ and that the head coil is positioned equally over the brain.
 
 ```{code-cell} python
 :tags: [hide-cell]
-fname = './assets/example-1_desc-corr_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+# ns.three_plane('./assets/example-1_desc-corr_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 ## Example 2
-Here is a 4D BOLD image that has been assessed with `MRIQC`:
+Here is a subject whose 4D BOLD images from a single session have been assessed with `MRIQC`:
 ```{code-cell} python
-fname = './assets/example-2_desc-orig_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+ns.three_plane('assets/example-2_run-01_acq.nii.gz', interactive=True, cmap='gray')
+```
+```{code-cell} python
+ns.three_plane('assets/example-2_run-02_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
-<!-- The `MRIQC` report is available [here]('./assets/example2_bold.html'). -->
+The `MRIQC` reports for [run 1](./assets/example-2_run-01_acq.html) and [run 2](./assets/example-2_run-02_acq.html) are also available.
 
-Can you spot the problem?
+Which run is better? Can you spot the problem?
 ```{hint}
 :class: dropdown
-Try looking at the *carpet plot*, generated by `MRIQC`, which facilitates viewing patterns across all voxels over time:
- <!-- ![carpetplot](./assets/example-2_desc-carpetplot_acq.svg) -->
+Try comparing the *carpet plots*, generated by `MRIQC`, which facilitate viewing patterns across all voxels over time.
+run 1:
+![run 1](./assets/example-2_run-01_desc-fmriplot_acq.svg)
+
+run 2:
+![run 2](./assets/example-2_run-02_desc-fmriplot_acq.svg)
 ```
 
 ```{admonition} What do you think the problem was?
@@ -86,21 +90,18 @@ Interestingly, this is not obvious in the mean image, which is justification to
 ```
 ```{code-cell} python
 :tags: [hide-cell]
-fname_mean = './assets/example-2_desc-mean_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+ns.three_plane('./assets/example-2_run-02_desc-tmean_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 ## Example 3
 Below is the first attempt at a structural image of a subject
 ```{code-cell} python
-fname = './assets/example-3_desc-orig_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+# ns.three_plane('./assets/example-3_desc-orig_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 Next, let's look at the structural image, *with the same scan parameters*, that was used for processing:
 ```{code-cell} python
-fname = './assets/example-3_desc-orig_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+# ns.three_plane('assets/example-3_desc-orig_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 ```{admonition} What is the difference between the two images??
@@ -115,18 +116,15 @@ Here are three multiparametric mapping images from a single subject acquired wit
 
 Session 1:
 ```{code-cell} python
-fname1 = './assets/example-4_ses-1_acq.nii.gz'
-ns.three_plane(fname1, interactive=True)
+# ns.three_plane('assets/example-4_ses-1_acq.nii.gz', interactive=True, cmap='gray')
 ```
 Session 2:
 ```{code-cell} python
-fname2 = './assets/example-4_ses-2_acq.nii.gz'
-ns.three_plane(fname2, interactive=True)
+# ns.three_plane('assets/example-4_ses-2_acq.nii.gz', interactive=True, cmap='gray')
 ```
 Session 3:
 ```{code-cell} python
-fname3 = './assets/example-4_ses-3_acq.nii.gz'
-ns.three_plane(fname3, interactive=True)
+# ns.three_plane('assets/example-4_ses-3_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 ```{admonition} Which image has the worst quality? What do you think the problem was?
@@ -141,8 +139,7 @@ In the second and third sessions, this was corrected by using a water-heater set
 Finally, we have this example of an EPI dataset.
 
 ```{code-cell} python
-fname = 'assets/example-5_acq.nii.gz'
-ns.three_plane(fname, interactive=True)
+ns.three_plane('assets/example-5_acq.nii.gz', interactive=True, cmap='gray')
 ```
 
 ```{admonition} What do you think the problem was?