reference.Rmd

---
title: "Reference"
date: "Last updated: `r format(Sys.time(), '%B %d, %Y')`"
bibliography: bibliography.bib
csl: american-medical-association.csl
link-citations: yes
output:
  html_document:
    toc: TRUE
    toc_depth: 2
    toc_float:
      collapsed: FALSE
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

```{r, child = c("js/back-to-top.html", "js/copy-to-clipboard.html", "js/tocify-offset.html")}
```

<br>

::: info
<i class="fa fa-info-circle" style="color: white"></i>&nbsp; The variables listed on this page are applicable to releases 3.3.0+ and are not necessarily correct for older versions of Gannet.
:::

## Pre-initializing Gannet

<br>

**Parent function**

`GannetPreInitialise.m`

<br>

| <u>Acquisition parameters</u> | <u>Description</u> |
|:------------------|:----------------------------------------------------|
| `target` | Sets the metabolite of interest that was edited in the MRS experiment; if HERMES or HERCULES was used, multiple metabolites should be selected |
| `ON_OFF_order` | Gannet automatically determines the order of editing pulses, but a usesr may manually input the order with this parameter |
| `seqorig` | Origin of the Philips MEGA-PRESS or GE HERMES sequences |

| <u>Analysis parameters</u> | <u>Description</u> |
|:------------------|:----------------------------------------------------|
| `LB` | Sets the amount of exponential line-broadening to apply to the data (in Hz)                                           |
| `water_ECC` | Whether to perform an eddy-current correction [@Klose1990] on the water data                                          |
| `metab_ECC` | Whether to perform an eddy-current correction on the metabolite data                                                  |
| `water_removal` | Whether to remove the residual water signal from the difference spectra using an HSVD filter [@Barkhuijsen1987]       |
| `alignment` | Which method to use for shot-to-shot frequency-and-phase correction [@Evans2013; @Near2015; @Mikkelsen2018; @Mikkelsen2020] |
| `use_prealign_ref` | In some cases, using `RobustSpecReg` to align HERMES/HERCULES data can result in worse alignment compared to the pre-aligned data; setting this parameter to 1 will make `RobustSpecReg` use the averaged pre-aligned subspectra as references to align the averaged post-aligned subspectra, which may improve the final alignment; this has not be tested extensively |
| `fit_resid_water` | Whether to model the residual water signal in the difference spectrum; used to calculate a water suppression factor |
| `weighted_averaging` | Whether to average the data using weighted averaging; the default approach use is mean-squared error, but other approaches can be set in `SignalAveraging.m` |

| <u>Flags</u> | <u>Description</u> |
|:------------------|:----------------------------------------------------|
| `HERMES`   | Set to `1` if the data were acquired using HERMES                                                                                         |
| `HERCULES` | Set to `1` if the data were acquired using HERCULES (`HERMES` must also be set to `1`)                                                    |
| `PRIAM`    | Set to `1` if the data were acquired using PRIAM                                                                                          |
| `phantom`  | Set to `1` if the data were acquired in a phantom                                                                                         |
| `join`     | Set to `1` to join multiple files (this can be batched across subjects)                                                                   |
| `mat`      | Set to `1` to save the output structure as a MAT-file                                                                                     |
| `csv`      | Set to `1` to export a CSV file containing useful data for statistical analysis (applies to `GannetFit.m`, `GannetSegment.m` and `GannetQuantify.m`) |
| `normalize` | Set to `1` to create voxel masks normalized to MNI152 space |
| `append`   | Set to `1` to append PDF outputs into one PDF (separately for each module) (requires `export_fig/` in the `Gannet/` directory to be added to the search path and <a href="https://www.ghostscript.com/" target="_blank">Ghostscript</a> to be installed on the user's machine (NB: macOS users should use <a href="https://pages.uoregon.edu/koch/" target="_blank">this version</a> or use <a href="https://formulae.brew.sh/formula/ghostscript" target="_blank">Homebrew</a> to install Ghostscript) |
| `hide`     | Set to `1` to not display output figures |

------------------------------------------------------------------------

## Loading & preprocessing

<br>

**Parent function**

`GannetLoad.m`

<br>

**Example usage:**

```{octave, eval = FALSE}
MRS_struct = GannetLoad({'S01_GABA_68_act.sdat'}, {'S01_GABA_68_ref.sdat'});
```

Output:

<img src="images/reference/GannetLoad-example.png" alt="A screenshot example of GannetLoad output">

A) Edited difference spectra before and after frequency and phase alignment. Users should look out for poor alignment and signal distortions from lipid contamination or ghosting artifacts [@Kreis2004].

B) The observed frequency of either the residual water signal or 3 ppm Cr peak on a average-by-average basis. Users can use this panel to check for participant motion and/or scanner-related frequency drift. The solid black line is the nominal water or 3 ppm Cr frequency, while the dashed lines represent +/-1 standard deviation of population-level frequency offsets observed in the Big GABA study [@Mikkelsen2017]. In other words, frequency shifts beyond these limits indicates above-average offsets that should be of concern to data fidelity.

C) A spectrogram of the 3 ppm Cr signal average by average before and after frequency and phase alignment. These data complement the data shown in panel B by additionally showing spectral distortions in each average.

D) Textual details of the data and processing procedures. When "n/a - wgt. avg. used" is shown for "Rejects", this means the data were averaged using weighted averaging, which down-weights bad (i.e., "rejected") averages.

------------------------------------------------------------------------

## Signal fitting

<br>

**Parent function**

`GannetFit.m`

<br>

**Example usage:**

```{octave, eval = FALSE}
MRS_struct = GannetLoad({'S01_GABA_68_act.sdat'}, {'S01_GABA_68_ref.sdat'});
MRS_struct = GannetFit(MRS_struct);
```

Output:

<img src="images/reference/GannetFit-example.png" alt="A screenshot example of GannetFit output">

A) Edited difference spectrum (spectra) with fitted model function(s) overlaid. The fit residuals are also shown. NB: When modeling the GABA peak, Gannet applies weights to the residual Cho signal data points at 3.16 to 3.285 ppm. This improves fitting of the GABA peak when there are subtraction artifacts.

B) Reference spectra (water and Cr) with fitted model functions overlaid. The fit residuals are also shown. If no water reference data was given during data loading, only Cr is shown.

C) Textual results from GannetFit (full details can be found on the [Data quality metrics](./data-quality-metrics.html) page). For the metabolites listed:
    - Area is the integrated signal (in arbitrary units) of the peaks shown
    - Linewidth is the full-width, half-maximum (FWHM) (in Hz)
    - SNR is defined as the signal model amplitude divided by twice the standard deviation of noise
    - Fit error is defined as the standard deviation of residuals divided by the signal model amplitude multiplied by 100
    - Quantification details can be found on the [Quantification & tissue correction](./quantification-tissue-correction.html) page.

------------------------------------------------------------------------

## Voxel co-registration

<br>

**Parent function**

`GannetCoRegister.m`

<br>

**Example usage:**

```{octave, eval = FALSE}
MRS_struct = GannetLoad({'S01_GABA_68_act.sdat'}, {'S01_GABA_68_ref.sdat'});
MRS_struct = GannetFit(MRS_struct);
MRS_struct = GannetCoRegister(MRS_struct, {'S01_struc.nii'});
```

Output:

<img src="images/reference/GannetCoRegister-example.png" alt="A screenshot example of GannetCoRegister output">

A) Co-registration of the MRS voxel on the corresponding structural MR image. The three orthogonal slices are shown at the voxel center.

B) Textual details of the voxel geometry.

------------------------------------------------------------------------

## Tissue segmentation

<br>

**Parent function**

`GannetSegment.m`

<br>

**Example usage:**

```{octave, eval = FALSE}
MRS_struct = GannetLoad({'S01_GABA_68_act.sdat'}, {'S01_GABA_68_ref.sdat'});
MRS_struct = GannetFit(MRS_struct);
MRS_struct = GannetCoRegister(MRS_struct, {'S01_struc.nii'});
MRS_struct = GannetSegment(MRS_struct);
```

Output:

<img src="images/reference/GannetSegment-example.png" alt="A screenshot example of GannetSegment output">

A) Axial view of the probabilistic voxel tissue segmentation maps for grey matter (GM), white matter (WM), and cerebrospinal fluid (CSF).

B) Textual details of the CSF-corrected metabolites values (see [Quantification & tissue correction](./quantification-tissue-correction.html) for further details) and the voxel tissue volume fractions.

------------------------------------------------------------------------

## Quantification

<br>

**Parent function**

`GannetQuantify.m`

<br>

**Example usage:**

```{octave, eval = FALSE}
MRS_struct = GannetLoad({'S01_GABA_68_act.sdat'}, {'S01_GABA_68_ref.sdat'});
MRS_struct = GannetFit(MRS_struct);
MRS_struct = GannetCoRegister(MRS_struct, {'S01_struc.nii'});
MRS_struct = GannetSegment(MRS_struct);
MRS_struct = GannetQuantify(MRS_struct);
```

Output:

<img src="images/reference/GannetQuantify-example.png" alt="A screenshot example of GannetQuantify output">

A) Axial view of the probabilistic voxel tissue segmentation maps for grey matter (GM), white matter (WM), and cerebrospinal fluid (CSF).

B)  Edited difference spectrum (spectra) with fitted model function(s) overlaid.

C) Textual details of tissue-corrected metabolite values (see [Quantification & tissue correction](./quantification-tissue-correction.html) for further details).

<br>

### References