Gannet 3.1 released

Introducing Gannet 3.1! This new version includes a number of updates and bug fixes. Notable additions include a new frequency-and-phase correction algorithm (robust spectral registration) and functionality for EtOH/GABA/GSH HERMES data.

Gannet 3.1 is available for immediate download at the following link: https://github.com/richardedden/Gannet3.1/archive/master.zip

Release notes:

MAJOR CHANGES

  • Adopted semantic versioning (see semver.org)

  • Aesthetic changes to PDF outputs throughout

  • Add functionality for processing and fitting of EtOH/GABA/GSH HERMES data

  • Introduced Robust_Spectral_Registration.m: robust correction of frequency/phase errors (recommended and default for all acquisition types)

  • If using Robust_Spectral_Registration.m, sub-spectra are averaged using weighted averaging; outlier removal is not applied in this case

  • nlinfit will no longer throw an error if peak model fitting is poor

  • GannetQuantify.m corrects metabolite measurements for partial tissue volume effects using the Gasparovic et al., 2006 (MRM) method; the Harris et al., 2015 (JMRI) method (alpha correction) is still also applied

MINOR CHANGES

  • Averaged HERMES sub-spectra are saved in MRS_struct.spec

  • HSVD water removal can be applied to all MEGA-PRESS and HERMES data (on by default)

  • Improved optimization parameters for frequency/phase alignment and peak model fitting

  • Turned off ignorable warnings that sometimes occur during peak model fitting in GannetFit.m

  • Fixed bugs in GannetMask_GE.m

  • Tissue fractions saved in MRS_struct.out renamed to fGM, fWM and fCSF

  • Text font in PDF outputs changed to Arial for cross-OS compatibility

  • More appropriate SNR thresholding in Spectral_Registration.m/Spectral_Registration_HERMES.m/Robust_Spectral_Registration.m

Gannet supports Siemens Hermes data

Gannet now provides support for Hermes data acquired using Siemens 3T scanner. The acceptable format is .dat. Please note that it is beneficial to acquire metabolite data and water data using the same sequence for better coil combination. Below is the GannetLoad window displaying Siemens HERMES data before and after post-processing steps in Gannet.

GABAmrs_website.jpg

Running a GSH-edited MEGA-PRESS dataset through Gannet 3.0

We have improved the data processing and quantification routines for GSH-edited MEGA-PRESS data in Gannet 3.0. Here is a quick "getting started" tutorial on running a GSH-edited MEGA-PRESS dataset:

  1. Download Gannet 3.0, placing the master folder at the top of your MATLAB's search path.

  2. Open GannetPreInitialise.m.

  3. Set MRS_struct.p.target to 'GSH' (MRS_struct.p.target2 can be ignored).

  4. Set MRS_struct.p.ONOFForder to 'offfirst' or 'onfirst' depending on the order of the ON/OFF editing pulses in your MEGA-PRESS acquisition (typically this should be 'offfirst' for Philips data and 'onfirst' for GE/Siemens data).

  5. Set MRS_struct.p.water_removal to 1 (this is the default) to remove residual water in the difference spectrum.

  6. Set MRS_struct.p.AlignTo to 'SpecRegHERMES'. (We recently published a novel frequency-and-phase correction algorithm for multiplexed edited MRS data [1]; this method also works well with GSH-edited data and is recommended.)

  7. Set MRS_struct.p.GSH_model to 'SixGauss' (recommended for long-TE MEGA-PRESS data).

  8. Save your changes.

  9. Change your working directory to where your GSH dataset is saved.

  10. To run GannetLoad on:

    1. GE data, run: MRS = GannetLoad({'GSH_MEGA_1.7'});

    2. Philips SDAT data (no water reference), run: MRS = GannetLoad({'GSH_MEGA_1_act.sdat'});

    3. Philips SDAT data (with water reference), run: MRS = GannetLoad({'GSH_MEGA_1_act.sdat'}, {'GSH_MEGA_1_ref.sdat'});

    4. Philips .data files (no water reference), run: MRS = GannetLoad({'GSH_MEGA_1.data'});

    5. Philips .data files (with water reference), run: MRS = GannetLoad({'GSH_MEGA_1.data'}, {'GSH_MEGA_1_water.data'});

    6. Siemens .rda data (no water reference), run: MRS = GannetLoad({'GSH_MEGA_1_ON.rda', 'GSH_MEGA_1_OFF.rda'});

    7. Siemens .rda data (with water reference), run: MRS = GannetLoad({'GSH_MEGA_1_ON.rda', 'GSH_MEGA_1_OFF.rda'},{'GSH_MEGA_1_water.rda'});

    8. Siemens TWIX data (no water reference), run: MRS = GannetLoad({'GSH_MEGA_1_metab.dat'});

    9. Siemens TWIX data (with water reference), run: MRS = GannetLoad({'GSH_MEGA_1_metab.dat'}, {'GSH_MEGA_1_water.dat'});

  11. Then run GannetFit: MRS = GannetFit(MRS);

 

1. Mikkelsen M, Saleh MG, Near J, et al. Frequency and phase correction for multiplexed edited MRS of GABA and glutathione. Magn. Reson. Med. 2017;0:1–8. doi: 10.1002/mrm.27027.

Running a HERMES dataset through Gannet 3.0

One of the new features of Gannet 3.0 is the ability to process and quantify edited MRS data acquired by HERMES (1–3). Here is a quick "getting started" tutorial on running a GABA-/GSH-edited HERMES dataset:

  1. Download Gannet 3.0, placing the master folder at the top of your MATLAB's search path.

  2. Open GannetPreInitialise.m.

  3. Set MRS_struct.p.target to 'GABAGlx' and MRS_struct.p.target2 to 'GSH' (these are the defaults).

  4. Set MRS_struct.p.ONOFForder to 'offfirst' if running a Philips HERMES dataset, or 'onfirst' if running a GE HERMES dataset.

  5. Set MRS_struct.p.water_removal to 1 (this is the default).

  6. Set MRS_struct.p.AlignTo to 'SpecRegHERMES'.

  7. Set MRS_struct.p.HERMES to 1.

  8. Save your changes.

  9. Change your working directory to where your HERMES dataset is saved.

  10. To run GannetLoad on:

    1. GE data, run: MRS = GannetLoad({'HERMES_1.7'});

    2. Philips data (with a water reference), run MRS = GannetLoad({'HERMES_1_act.sdat'},{'HERMES_1_ref.sdat'});

  11. Then run GannetFit: MRS = GannetFit(MRS);

 

1. Chan KL, Puts NAJ, Schär M, Barker PB, Edden RAE. HERMES: Hadamard encoding and reconstruction of MEGA-edited spectroscopy. Magn. Reson. Med. 2016;76:11–19. doi: 10.1002/mrm.26233.

2. Saleh MG, Oeltzschner G, Chan KL, Puts NAJ, Mikkelsen M, Schär M, Harris AD, Edden RAE. Simultaneous edited MRS of GABA and glutathione. NeuroImage 2016;142:576–582. doi: 10.1016/j.neuroimage.2016.07.056.

3. Chan KL, Saleh MG, Oeltzschner G, Barker PB, Edden RAE. Simultaneous measurement of Aspartate, NAA, and NAAG using HERMES spectral editing at 3 Tesla. NeuroImage 2017;155:587–593. doi: 10.1016/j.neuroimage.2017.04.043.

Gannet 3.0 released

Introducing Gannet 3.0! This new version includes a number of new data processing features (incl. handling of HERMES data), a revamped output MATLAB structure, slight improvements in speed and efficiency and many other changes and bug fixes.

Gannet 3.0 is available for immediate download at the following link: https://github.com/richardedden/Gannet3.0/archive/master.zip

Release notes:

MAJOR CHANGES

+ Added new puffin logo
+ Changes to output structure to accommodate multi-metabolite and multi-voxel datasets
+ Removed unused/redundant lines of code throughout Gannet
+ Removed historical/unused .m files in Gannet folder
+ Optimized code where possible, e.g.:
    - Removing loops and vectorizing instead
    - Simplifying code, e.g., using one-line logical indexing for frequency ranges
    - Pre-allocating memory by setting up variables with zeros
    - Removed ‘convergence’ loop in metabolite signal fitting (should be enough to first run lsqcurvefit followed by nlinfit with high enough max iterations/low enough tolerances)
+ A number of updates to ‘PhilipsRead.m’, ‘GERead.m’ and ‘SiemensTwixRead.m’, e.g.:
    - Almost all acquisition parameters now parsed from the header
    - For P-files and TWIX data, coil combination/pre-phasing is performed by signal-weighting method using unsuppressed water data (when available)
    - Complete revamping of ’SiemensTwixRead.m’; automatic determination of MEGA-PRESS sequence type and scanner software version; removed this parameter from ‘GannetPreInitialise.m’
    - For Philips HERMES data, only the averages where editing pulses do not affect residual water are used for pre-phasing (currently geared towards GABA-/GSH-edited data)
+ Added support for DICOM MRS data files
+ Added functions to de-identify GE P-files, Philips SDAT/SPAR files and Siemens TWIX files
+ SPM segmentation now called by either ‘CallSPM8segmentation.m’ or ‘CallSPM12segmentation.m’ depending on which version of SPM is installed

GannetLoad:
+ Data are now zero-filled to obtain a nominal spectral resolution of 0.061 Hz/point by default (to handle acquisitions with number of data points/spectral width other than 2048/2000 Hz); removed this parameter from ‘GannetPreInitialise.m’
+ HSVD water filter is applied to both GABA-/GSH-edited HERMES data, and to both pre- and post-aligned DIFF spectra
+ For filtered HERMES data, baseline correction performed by demeaning (real) signal between 9 and 10 ppm

Spectral_Registration:
+ Now only first n points of FIDs used for registration, where n is the last point where SNR > 3
+ By default, median across data points of all transients is used as the reference ‘FID’
+ Frequency/phase offset estimates now saved for each processed dataset
+ Transients are now rejected if their respective standardized mean square error (from the nonlinear regression routine) exceeds +/-3 stds.
+ Added ‘Spectral_Registration_HERMES.m’ for frequency/phase correction of HERMES data

GannetFit:
+ GABA+Glx model fitting now performed by weighted nonlinear regression, where observation weights are supplied in nlinfit to down-weight any Cho subtraction artifact and (for HERMES data only) co-edited(?) signals downfield of 3.7 ppm Glx signal (thanks to Alex Craven of University of Bergen for this idea)
+ Added fitting of residual water in MEGA-PRESS data to calculate water suppression factor
+ Added fitting of NAA signal in OFF spectrum


MINOR CHANGES

+ Lots of minor bug fixes
+ Renamed module output folders to ‘Gannet*_output’ (e.g., ‘GannetLoad_output’)
+ Renamed module output PDFs to ‘<filename>_*.pdf’ (e.g., ‘S01_GABA_load.pdf*)
+ Text in output figures aligned more cleanly
+ Addressed MATLAB warnings
+ Made code easier to read/understand by indenting lines and adding a header comment here and there at beginning of processing steps
+ Optimization options for lsqcurvefit and nlinfit now set consistently throughout Gannet
+ Renamed some variables for the sake of consistency
+ Output figures now open in center of screen regardless of screen resolution (figure pixel dimensions are fixed, however)
+ When batch-processing, each output figure is cleared rather than closed all together
+ Some useful acquisition parameters (e.g., edit pulse frequencies) are parsed from the data file headers (and saved in vendor-specific fields) where available

GannetLoad:
+ Fixed ON/OFF indices for GABA-/GSH-edited HERMES data (for ‘offfirst’ only); assumes ‘C B A D’ as per NeuroImage paper
+ Color of pre-/post-alignment spectra now fixed to red/blue regardless of user’s MATLAB version
+ Post-alignment spectra always plotted second so that they are displayed in the foreground (this is helpful for HERMES data)
+ Renamed ‘SiemensRead_RE.m’ to ‘SiemensRead.m’
+ Renamed ‘Gannetplotprepostalign.m’ to ‘GannetPlotPrePostAlign.m’

GannetFit:
+ Water-scaled ON and OFF spectra now saved along with water-scaled DIFF spectrum
+ Models always plotted second so that they are displayed in the foreground
+ Renamed ‘GaussModel_area’, ‘GABAGlxModel_area’, etc. to ‘GaussModel’, GABAGlxModel’, etc.
+ Renamed ‘MRSGABAinstunits’ to ‘CalcInstUnits’
+ Improved quantification of lactate

Gannet Supporter Pro License

At Gannet HQ, we spend a lot of time listening to the podcasts provided by maximumfun.org, including the life-changingly wonderful Judge John Hodgman. This podcast network runs on the basic assumption that people who like something might be willing to support it financially.  So I thought it might be worth trying for Gannet.

If you like Gannet and would like to support the work we do, please consider purchasing a Gannet Supporter Pro License.  When you do so, you will be sent a beautiful t-shirt from Zazzle, that you can wear to your conference of choice, and to bars, and at a push weddings.

Depending on how this appears on your credit card statement, it might even be a  claimable expense.  Net proceeds from sales of Gannet Pro Supporter Licenses will be used to purchase coffee and further fuel the development of the software.

If you are a female supporter of Gannet, Zazzle will allow you to choose a lady-shaped t-shirt option.  

Gannet remains a free-to-use software.  Thank you for using and supporting Gannet.

 

GannetCoRegister for Siemens

We receive a number of support requests on GannetCoRegister for Siemens. We hope that Gannet’s co-registration for Siemens data does the correct job in most cases. However, on occasion, there can be hiccups. This post attempts to explain their origin, how to avoid them, and how to fix them.

RECONSTRUCTION

At first glance, it seems trivial to correctly draw a box on a brain. Unfortunately, it is not, and the process has pitfalls. One reason is a lack of standardization and documentation. Unlike imaging metadata (at least some of which are agreed upon in DICOM fields), there is no universal vendor-independent data structure that carries the parameters of an MRS voxel, that is, dimension, position and rotation. Siemens, Philips and GE all have their own conventions and formats of defining and storing the voxel parameters, and they may even vary between sequence and/or software versions.

On top of that, the rotated-and-offset voxel is usually planned in the context of an oblique-and-offset anatomical image. Sometimes, the image on which the voxel is planned is not the one it is intended to be coregistered to. That makes three frames of reference, which may not even share the same coordinate system, e.g. when the table moves during scans. 

SOME GOLDEN RULES

Despite a few caveats, GannetCoRegister will very likely work smoothly for you, if you adhere to a few Golden Rules.

  • Place your voxel in the image that you want to use for coregistration. This is usually an axial 3D MPRAGE. It is common to acquire three separate orthogonal 2D scans for voxel planning, because the Siemens software does not automatically provide sagittal and coronal reconstructions of the MPRAGE. We would encourage users not to do this - reconstruct the T1 manually, or ask your tech for help!

  • If the above is not possible, make sure that all your images are acquired in REF or FIXED mode. Running a sequence in ISO mode will reset the isocenter, move the table, and create a new frame of reference.

  • Take screenshots of each planned voxel.

  • Double check the reconstructed voxel for each dataset. Thoroughly compare it to the screenshot taken while planning the voxel on the scanner. See the Troubleshooting section below if you believe the reconstruction is not correct.

If you follow these, and still meet with issues, please let us know, so we can revise or further clarify them.

TROUBLESHOOTING

If your reconstructed voxel does not appear correct, you may try the following fixes:

  • If the voxel appears to be in the correct position, but the dimensions (or rotations) look swapped, you can edit GannetMask_Siemens.m (lines 80-83 as of today).

MRS_struct.p.voxoff = [rda.VOIPositionSag rda.VOIPositionCor rda.VOIPositionTra];
MRS_struct.p.voxsize = [rda.VOIThickness rda.VOIReadoutFOV rda.VOIPhaseFOV];
MRS_Rot(:,1) = rda.row.'.* [-1 -1 1]';
MRS_Rot(:,2) = rda.column.';

The first line determines the voxel offset (and should be fine in all cases). The second line determines the voxel dimensions, while the third and fourth rotate the voxel in space. You may try to swap the dimension variables, or modify the -1 and 1 values in the multiplication array.

  • If you have planned your voxel in an image other than your MPRAGE and get wrong results, you can try fixing this with SPM. Coregister (estimate & reslice) your MPRAGE to the image you used for planning, and feed the new image to GannetCoRegister. This will reconcile the coordinate systems defined in the nifti headers, but the coregistration of the two images might be suboptimal (depending on the quality of the planning image).

Please let us know when you encounter difficulties using GannetCoRegister or GannetSegment, along with the specific sequence and Siemens software version you are using. Your feedback will help improve future versions of Gannet!