-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.Rmd
executable file
·194 lines (124 loc) · 9.83 KB
/
index.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
---
title: "Gannet"
date: "Last updated: `r format(Sys.time(), '%B %d, %Y')`"
output: html_document
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
```{r, child = "js/back-to-top.js"}
```
<br>
<img id="img_50" src="images/logo+title.png" alt="The Gannet logo"/>
::: release
<h3>Current stable release: <a href="https://github.com/markmikkelsen/Gannet" target="_blank" class="badge badge-secondary">3.3.2</a></h3>
:::
## Overview
Gannet is a free, open-source MATLAB-based software toolkit for analyzing edited single-voxel ^1^H magnetic resonance spectroscopy (MRS) data. Its largely automated functions cover all the essential steps of modern MRS analysis:
- Loading raw data files
- Several preprocessing steps
- Signal modeling
- Voxel co-registration to and segmentation of structural MR images
- Metabolite concentration estimation corrected for tissue composition
Several existing software packages for MRS data analysis require substantial user input or offer a wide selection of processing options. In contrast, the philosophy behind Gannet is to provide users with a complete automated pipeline without the need for significant user input.
Additionally, as open-source software, advanced users have the ability to modify the underlying routines for ad hoc purposes.
## Installation
### Prerequisites
Gannet runs in <a href="https://mathworks.com/products/matlab.html" target="_blank">MATLAB</a>. For best performance, we recommend using the latest release of MATLAB if possible. Additionally, Gannet requires that the following MATLAB toolboxes are installed:
- Image Processing
- Optimization
- Signal Processing
- Statistics and Machine Learning
You can check which toolboxes you have installed by typing `ver` in the MATLAB command window. To install any missing toolboxes, please follow these <a href="https://mathworks.com/matlabcentral/answers/101885-how-do-i-install-additional-toolboxes-into-an-existing-installation-of-matlab" target="_blank">instructions</a>.
To run the voxel co-registration and structural image segmentation modules, <a href="https://www.fil.ion.ucl.ac.uk/spm/software/spm12/" target="_blank">SPM12</a> must be installed.
### Download
The simplest way to install Gannet is to download the latest source code as a ZIP file from the <a href="https://github.com/markmikkelsen/Gannet" target="_blank">GitHub repository</a> and move the `Gannet-main/` directory into your main MATLAB directory (or wherever else you wish).
Alternatively, Git users can clone the Gannet repository into a directory of their choice:
```{verbatim, eval = FALSE}
git clone https://github.com/markmikkelsen/Gannet.git
```
The development version of Gannet can be downloaded from the <a href="https://github.com/markmikkelsen/Gannet/tree/dev" target="_blank">development branch</a> on GitHub or by using the following Git command if the repository was cloned:
```{verbatim, eval = FALSE}
git checkout dev
```
Stable releases can be found <a href="https://github.com/markmikkelsen/Gannet/releases" target="_blank">here</a>.
### Setup
Open the *Set Path* dialog box from the MATLAB menu (or run the command `pathtool` in the Command Window), click *Add with Subfolders...*, find the downloaded Gannet directory, and then select it. When done, press *Save* to permanently save the Gannet directory to MATLAB's default search path.
SPM12 can be installed in the same manner after it has been downloaded from the <a href="https://www.fil.ion.ucl.ac.uk/spm/software/spm12/" target="_blank">SPM</a> website.
::: info
<i class="fa fa-info-circle" style="color: white"></i> It is highly recommended that you only add the main SPM12 directory (`spm12/`) to your search path instead of including all the subdirectories. This prevents function conflicts.
:::
::: warning
<i class="fa fa-exclamation-circle" style="color: white"></i> If you have <a href="https://github.com/schorschinho/osprey" target="_blank" style="color:white"><u>Osprey</u></a> also installed on your computer, please ensure that you either have all the Gannet and SPM12 directories at the top of your search path or have removed the Osprey directories from your search path. Gannet and Osprey share several functions that can lead to conflicts that result in Gannet not functioning correctly.
:::
## Compatibility
Gannet is currently being developed in MATLAB R2024b in macOS 15 Sequoia (Apple silicon). While reasonable effort is made to ensure legacy and cross-OS compatibility, an error-free user experience is not guaranteed.
## Supported file formats
At present, the following MRS data file formats are supported:
- DICOM (.dcm)
- GE P-file (.7)
- NIfTI-MRS (.nii[.gz])
- Philips .data/.list
- Philips .raw
- Philips .sdat/.spar
- Siemens DICOM (.ima)
- Siemens .rda
- Siemens TWIX (.dat)
For creating and co-registering voxel masks, structural images need to be in NIfTI format (DICOM files can also be used if processing GE P-files).
::: warning
<i class="fa fa-exclamation-circle" style="color: white"></i> Philips users: Do not use structural images exported using the *fsl-nifti* option as this creates problems with co-registration in Gannet.
:::
## Getting help
If you encounter any problems, please first check the Documentation or [FAQ](https://markmikkelsen.github.io/Gannet-docs/faq.html) for a solution.
Otherwise, you can post your query on the <a href="https://forum.mrshub.org/c/mrs-software/gannet/9" target="_blank">Gannet forum</a> on <a href="https://mrshub.org/" target="_blank">MRSHub</a>.
The Gannet team can also be <a href="mailto:[email protected]?subject=[Gannet]%20<Please enter the subject of your query here>" target="_blank">contacted</a> directly. We will do our best to work with you to solve your issue.
## Versioning
Gannet uses a form of <a href="https://semver.org/" target="_blank">semantic versioning</a> in the style 'x.x.x' to mark code releases. Versioning is also conducted on a module-specific basis using the style 'YYMMDD'. That is, each Gannet module has its own release version. Users should note that module-specific versions sometimes are updated despite the semantic version number remaining unchanged (typically for minor updates/bug fixes).
## Developers
- Richard Edden (Johns Hopkins University) - creator
- Mark Mikkelsen (Weill Cornell Medicine) - lead developer
- Georg Oeltzschner (Johns Hopkins University) - contributor
- Muhammad Saleh (Children's Hospital of Philadelphia) - contributor
- C. John Evans (Cardiff University) - contributor
- Ashley Harris (University of Calgary) - contributor
- Nicolaas Puts (King's College London) - contributor
## License and citing Gannet
This software is licensed under an open-source [BSD-3-Clause License](https://markmikkelsen.github.io/Gannet-docs/gannet-license.html). Should you disseminate material that made use of Gannet, please cite the following publications, as appropriate:
- Edden RAE, Puts NAJ, Harris AD, Barker PB, Evans CJ. <a href="https://doi.org/10.1002/jmri.24478" target="_blank">Gannet: A batch-processing tool for the quantitative analysis of gamma-aminobutyric acid-edited MR spectroscopy spectra.</a> *Journal of Magnetic Resonance Imaging*. 2014;40(6):1445--1452
**If you perform frequency-and-phase correction (FPC) using:**
Robust spectral registration (`RobustSpecReg`):
- Mikkelsen M, Tapper S, Near J, Mostofsky SH, Puts NAJ, Edden RAE. <a href="https://doi.org/10.1002/nbm.4368" target="_blank">Correcting frequency and phase offsets in MRS data using robust spectral registration.</a> *NMR in Biomedicine*. 2020;33(10):e4368
multi-step FPC (`SpecRegHERMES`):
- Mikkelsen M, Saleh MG, Near J, et al. <a href="https://doi.org/10.1002/mrm.27027" target="_blank">Frequency and phase correction for multiplexed edited MRS of GABA and glutathione.</a> *Magnetic Resonance in Medicine*. 2018;80(1):21--28
or spectral registration (`SpecReg`):
- Near J, Edden R, Evans CJ, Paquin R, Harris A, Jezzard P. <a href="https://doi.org/10.1002/mrm.25094" target="_blank">Frequency and phase drift correction of magnetic resonance spectroscopy data by spectral registration in the time domain.</a> *Magnetic Resonance in Medicine*. 2015;73(1):44--50
**If you perform voxel co-registration:**
- Please acknowledge the use of SPM12. You may also link/cite the <a href="https://www.fil.ion.ucl.ac.uk/spm/software/spm12/" target="_blank">SPM12 website</a>.
**If you perform tissue segmentation:**
- Ashburner J, Friston KJ. <a href="https://doi.org/10.1016/j.neuroimage.2005.02.018" target="_blank">Unified segmentation.</a> *NeuroImage*. 2005;26(3):839--851
**If you report water-referenced, tissue-corrected metabolite measurements using:**
The Harris et al. method:
- Harris AD, Puts NAJ, Edden RAE. <a href="https://doi.org/10.1002/jmri.24903" target="_blank">Tissue correction for GABA-edited MRS: Considerations of voxel composition, tissue segmentation, and tissue relaxations.</a> *Journal of Magnetic Resonance Imaging*. 2015;42(5):1431--1440
or the Gasparovic et al. method:
- Gasparovic C, Song T, Devier D, et al. <a href="https://doi.org/10.1002/mrm.20901" target="_blank">Use of tissue water as a concentration reference for proton spectroscopic imaging.</a> *Magnetic Resonance in Medicine*. 2006;55(6):1219--1226
## Acknowledgments
The development and dissemination of Gannet has been supported by the following National Institutes of Health (NIH) grants:
- R01 EB016089
- R01 EB023963
- P41 EB015909
- K99 EB028828
- R01 MH106564
- R21 MH098228
- R21 NS077300
- R01 MH096263
We wish to thank the following individuals for their direct or indirect contributions:
- Yair Altman (Undocumented Matlab)
- Peter Barker (Johns Hopkins University)
- Alex Craven (University of Bergen)
- Philipp Ehses (Max Planck Institute for Biological Cybernetics)
- Robin de Graaf (Yale School of Medicine)
- Xiangrui Li (Ohio State University)
- Jamie Near (McGill University)
- Ralph Noeske (GE HealthCare)
- Wouter Potters (UMC Amsterdam)
- Jan Simon (Heidelberg)