-
Notifications
You must be signed in to change notification settings - Fork 0
/
reference.Rmd
executable file
·224 lines (143 loc) · 9.94 KB
/
reference.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
---
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 = "js/back-to-top.js"}
```
<br>
::: info
<i class="fa fa-info-circle" style="color: white"></i> 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 |
| `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`) |
| `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](https://markmikkelsen.github.io/Gannet-docs/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](https://markmikkelsen.github.io/Gannet-docs/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](https://markmikkelsen.github.io/Gannet-docs/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](https://markmikkelsen.github.io/Gannet-docs/quantification-tissue-correction.html) for further details).
<br>
### References