Merge pull request #7 from eilidhmacnicol/main

Adding animal-qc hands-on material

docs/_toc.yml

@@ -17,6 +17,8 @@ parts:
   - file: animal-qc/intro
   - file: animal-qc/acquisition
   - file: animal-qc/processing
+  - file: animal-qc/acquisition_examples
+  - file: animal-qc/processing_examples
 - caption: Automating QA
   chapters:
   - file: auto-qc/intro

docs/animal-qc/acquisition.md

@@ -11,25 +11,26 @@ difficult to obtain.
 
 ## Hardware
 ### Magnet field strength
-The scanner's field strength, which range from 4.7 to 16.4 Tesla, can itself
+The scanner's field strength, which typically ranges from 4.7 to 16.4 Tesla for preclinical imaging, can itself
 have many impacts on the data quality: higher field strength
-provides higher signal-to-noise ratios in shorter acquisition times, but it also
+provides higher signal-to-noise ratios, but it also
 exacerbates many types of artifacts.
 ### Scanner manufacture
 Bruker currently has a monopoly in preclinical imaging, but many sites have older scanners from other manufacturers.
 Those with Bruker scanners may also have a maintenance package which includes tests
 for quality assurance.
 ### Coils
-Volume coils require manual tuning (at least) daily.
-For scanners from out-of-business manufacturers, "homemade" coils are more common
-and less standardised.
+Some volume coils require manual tuning.
+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_
+include pulse oximeters and/or invasive blood pressure monitoring.
+### 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.
@@ -39,14 +40,13 @@ These facilitate support of the animal in the scanner and reduce movement.
 Related to scanner manufacture, is the software used to acquire and reconstruct
 the images.
 Bruker's software, Paravision, has several versions available.
-Paravision generates `2dseq` files rather than the `DICOM` images commonly
+Paravision generates `2dseq` files and can export `DICOM` images commonly
 generated by human scanners.
-Consequently, conversion to standardised naming formats requires specialised
-software that can work with these proprietary files.
+However, storage of metadata may not always be consistent with human imaging standards.
 ### Other software
 Similarly, various software is available for monitoring physiology which is
 discussed at length [below](#physiology).
-As the animals are often anaesthetised task-based fMRI is less common.
+As the animals are often anaesthetised, task-based fMRI is less common.
 Instead, experiments may generate evoked-responses to some stimulus (e.g.
 stimulating a paw with electricity) in the scanner.
 Thus, software is also required to synchronise the stimulus onset to the scanning
@@ -64,7 +64,7 @@ still.
 This difference in scale necessitates the increased magnet field strength but the change in field strength is not proportional to the change in size.
 ### Tissue differences
 The proportion of white matter in rodents is smaller than that in humans.
-Since white matter bundles are much less distinct in rats and mice, the MR 
+Since white matter bundles are much less distinct in rats and mice, the MR
 signal contrast between the two tissue types is often less well-defined.
 
 Additionally, the olfactory bulb is much larger in rodents than in humans and there
@@ -78,8 +78,7 @@ equivalent.
 Additionally, I have noticed confusion in the convention for naming the scanner
 orientations.
 Humans most often enter the scanner supine along the axis that aligns
-with that of B0 so the B1 field aligns with the anterior-posterior plane, and the
-B0 field axis aligns with the superior-inferior axis.
+with that of B0, i.e., the B0 field axis aligns with the superior-inferior axis.
 Rodents are likely to be prone (although not always) and because of the difference
 in anatomical orientation described above, the posterior-anterior plane in
 quadripeds aligns with the B0 field axis.
@@ -88,7 +87,7 @@ Thus orientation may be "scanner-oriented" (where the axes aligns with the magne
 field directions) or "subject-oriented" (where the axes align with the anatomy of
 the subject).
 ### Strain
-There may be differences in anatomy or physiology that come from differences in 
+There may be differences in anatomy or physiology that come from differences in
 species strain.
 In particular, genetically modified animals may be more susceptible to larger
 ventricular compartments.
@@ -104,15 +103,16 @@ with benefits and costs.
 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 cannulation</li><li>requires Atipamezole for speedy recovery</li>
-Alpha-Chloralose | infusion |<li> preserves BOLD response </li> | <li>Difficult recovery</li>
-Ketamine | infusion | |
+(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 | <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
@@ -121,16 +121,16 @@ Consequently, internal body temperature is recorded with a thermometer.
 It is possible to use the thermometer reading as part of a feedback loop
 controlling either a water heating system (built in to the bed or applied as a
 heated blanket) or an air heating system (which is blown through the scanner bore
-with a fan).
+with a fan) with all the possible problems related to frequency shifts and drifting that could affect the scans.
 
 Since temperature is critical for the rate of oxygen consumption, temperature should be maintained within a small normative range.
 ### Movement
-Movement is often reduced in scanning animal imaging due to the use of bite bars,
+Movement is often reduced in animal imaging due to the use of bite bars,
 ear bars, and anaesthesitics and sedatives.
 However, movement should still be carefully scrutinized as it may point to:
 - less anaesthetised/sedated state
 - movement associated with the onset of a task (e.g. jumping at stimulus)
-- scanner drift 
+- scanner drift
 
 ## Hands-on
 Let's see some of these factors in action.

docs/animal-qc/acquisition_examples.md

@@ -0,0 +1,154 @@
+---
+jupytext:
+  formats: md:myst
+  notebook_metadata_filter: all,-language_info
+  split_at_heading: true
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: '0.8'
+    jupytext_version: 1.11.2
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+```{code-cell} python
+:tags: [remove-cell]
+# Some configurations to "beautify" plots
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+mpl.rcParams["font.family"] = "Libre Franklin"
+plt.rcParams["axes.facecolor"] = "white"
+plt.rcParams["savefig.facecolor"] = "white"
+```
+
+# "What went wrong?" data acquisition edition
+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.
+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.
+
+Such criteria could include the quality metrics generated by `MRIQC`, which are objective measurements
+that can be used for defining quality cut offs.
+
+Let's go through some examples where the images acquired have not met such criteria.
+
+## Example 1
+Let's start off with an easy one: below is a T2-weighted structural image.
+```{code-cell} python
+import nanslice.jupyter as ns
+%matplotlib widget
+
+# ns.three_plane('./assets/example-1_desc-orig_acq.nii.gz', interactive=True, cmap='gray')
+```
+
+```{admonition} What do you think the problem was?
+:class: dropdown
+A badly positioned coil!
+
+*To correct for this*, make sure that the brain is located in the isocentre of the scanner, 
+and that the head coil is positioned equally over the brain.
+```
+
+```{code-cell} python
+:tags: [hide-cell]
+# ns.three_plane('./assets/example-1_desc-corr_acq.nii.gz', interactive=True, cmap='gray')
+```
+
+## Example 2
+Here is a subject whose 4D BOLD images from a single session have been assessed with `MRIQC`:
+```{code-cell} python
+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` reports for [run 1](./assets/example-2_run-01_acq.html) and [run 2](./assets/example-2_run-02_acq.html) are also available.
+
+Which run is better? Can you spot the problem?
+```{hint}
+:class: dropdown
+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?
+:class: dropdown
+The animal moved in the last part of the scan, removing their head entirely from the cradle and head coil.
+
+Interestingly, this is not obvious in the mean image, which is justification to check the whole time course and not just some volumes!
+```
+```{code-cell} python
+:tags: [hide-cell]
+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
+# 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
+# ns.three_plane('assets/example-3_desc-orig_acq.nii.gz', interactive=True, cmap='gray')
+```
+
+```{admonition} What is the difference between the two images??
+:class: dropdown
+**Wrong coil configuration!**
+The first image did not have the correct coil configuration.
+In particular, the head coil was not set as the receiver coil.
+```
+
+## Example 4
+Here are three multiparametric mapping images from a single subject acquired with the same protocol in three separate scanning sessions.
+
+Session 1:
+```{code-cell} python
+# ns.three_plane('assets/example-4_ses-1_acq.nii.gz', interactive=True, cmap='gray')
+```
+Session 2:
+```{code-cell} python
+# ns.three_plane('assets/example-4_ses-2_acq.nii.gz', interactive=True, cmap='gray')
+```
+Session 3:
+```{code-cell} python
+# 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?
+:class: dropdown
+Changing air temperature!
+
+The set up to maintain the mouse's body temperature in the first session used a fan blowing thermostatically-controlled air into the scanner bore.
+In the second and third sessions, this was corrected by using a water-heater set up.
+```
+
+## Example 5
+Finally, we have this example of an EPI dataset.
+
+```{code-cell} python
+ns.three_plane('assets/example-5_acq.nii.gz', interactive=True, cmap='gray')
+```
+
+```{admonition} What do you think the problem was?
+:class: dropdown
+This is a ghosting artifact caused by the scan protocol.
+
+This particular protocol was acquiring too many slices in too short a window.
+If you are testing a new scan protocol, always have an optimised version before you start acquiring the data for a study.
+
+A walk-through acquisition the day before the study starts is highly recommended if it can be budgeted for (in time and money).
+```
+