GannetMask for Philips:beta version on github

We've been working on GannetMask and GannetCoRegister, tools for locating the MRS voxel within a structural image. In the first instance, we are releasing the code for Philips data, but
we are working on getting this code straight for GE and Siemens data as well.  Over the last eight years, I've tried to put code like this together at least two other times, investing weeks without success, so I am excited to have finally cracked it.  A big thanks to Paul Mullins for letting us look over his code - the big change that has made us successful this time around is to follow Paul's roadmap of letting SPM tools figure out the spatial location of each image pixel, and defining the MRS voxel by the coordinates of its corners.  You end up with far fewer painful coordinate-frame-changes to get wrong!
The github repository https://github.com/cjohnevans/Gannet2.0 has our current working versions of this code, although it is still evolving daily, as we run further tests.

Overview

We have developed two approaches for co-registering an MRS voxel to a T1 structural image: GannetMask and GannetCoRegister.  They allow a binary mask of the MRS voxel location to be created with the same geometry as the T1 image.  GannetMask is a stand-alone tool that will output a voxel mask image for a given pair of MRS and image files.  It can be used manually.  GannetCoRegister incorporates GannetMask into the Gannet workflow, generating a series of voxel masks for each of a batch of MRS files that have been processed with GannetLoad.

Requirements

1.     MRS .spar files

These tools rely upon MRS data output as .spar files.  Since MRS data processing performs better with .data filetype (which does not store location information), we strongly recommend exporting .sdat AND .data files.

2.      T1 .nii images

T1 (or other contrast) images must be exported from the scanner in .nii format, using the nii option, not the FSL nii option.

3.      SPM8  installation

GannetMask makes use of SPM to interpret the .nii header and calculate the 3D spatial coordinates of each image pixel. SPM is also useful for segmentation of T1 images to determine voxel fractions of gray and white matter, and CSF.  SPM 8 can be downloded from http://www.fil.ion.ucl.ac.uk/spm/software/spm8/.

GannetMask

GannetMask can be run from the matlab command line using:

GannetMask('MRS_file.spar','imagefile.nii');

From a directory which contains the MRS_file.spar and image_file.nii.  GannetMask will save a file MRS_file_mask.nii in the same directory.

GannetCoRegister

GannetCoRegister is run from the command line after GannetLoad. 

MRS_struct = GannetLoad({'MRS_file1.sdat' });

MRS_struct = GannetCoRegister(MRS_struct, {'image1.nii’});

If a batch is being run, .nii image files are input to GannetCoRegister in the same way as the original files are input to GannetLoad (i.e. as a cell array of filenames).

MRS_struct = GannetLoad({'MRS_file1.sdat' 'MRS_file2.sdat'});

MRS_struct = GannetCoRegister(MRS_struct, {'image1.nii’ 'image2.nii'});

GannetCoRegister outputs one MRS_file1_mask.nii for each MRS dataset.  It also saves a pdf image of the voxel overlaid on a 3-plane view of the image at planes that transect the voxel.

NEW Gannet functionality: Saving the GannetFit output structure

Until now, it has been necessary to use matlab's save function to manually save the MRS-struct after a batch analysis.  This is fine, but easily forgotten, and re-doing full analyses can take time for large datasets.  Equally, saving the structure for every analysis gets tiresome and datasome.

Now we have added MRS_struct.p.mat which is set in GannetPreInitialise.m as a binary switch, to decide whether or not to save the MRS_struct as MRS_struct.mat.  If set to 1, the output is saved to the GannetFit folder.  NOTE that the folder is date-stamped but the filename is fixed, so analyses run on separate days will be kept separate, but analyses run on the same day in the same working directory will over-write the .mat file output.

PaperPlot just got better!

PaperPlot now supports three input formats:

PaperPlot(MRS_struct)

This will plot the spectrum and best-fit model for the first dataset in your structure.

PaperPlot(MRS_struct.spec.freq,MRS_struct.spec.diff)

This will plot the GABA MRS spectrum for the x and y values specified.

and
PaperPlot(MRS_struct.spec.freq,MRS_struct.spec.diff,plot_options)
As with the second option, it is possible to also specify plot options e.g. 'k' for black lines, as accepted by matlab's plot function.

To save for publication, save the matlab figure as .eps format.  Vector graphics saved as pdf do not come out right.  Then edit in Adobe Illustrator...

NEW Gannet functionality: PaperPlot

PaperPlot is a helpful tool for plotting isolated spectra for publication.

The syntax is:

PaperPlot(MRS_struct.spec.freq,MRS_struct.spec.diff,'k')

This will plot a tidy spectrum from 0.5 ppm to 4.5 ppm, with reversed "MRS" ppm axis and no y-axis values.  To save for publication, save the matlab figure as .eps format.  Vector graphics saved as pdf do not come out right.  Then edit in Adobe Illustrator...

Review Recommendation

A closing highlight from the GABA section:

"Overall GABA levels are therefore better markers of GABAergic tone (i.e. levels of tonic inhibition) than of inhibitory activity per se."

Gannet 2.0 release

We are pleased to announce the release version of Gannet 2.0 is available.  It can be downloaded from github: http://github.com/cjohnevans/Gannet2.0/archive/master.zip.

Gannet 2.0 has a number of improvements over previous versions, including:

• Gannet manual
• Re-organisation of the output structure MRS_struct, and stratification into:
• Parameters MRS_struct.p.*
• Time-domain data MRS_struct.fids.*
• Frequency-domain data MRS_struct.spec.*
• Output MRS_struct.out.*
• Improved frequency and phase correction using Jamie Near's Spectral Registration method
• Introduction of GannetPreInitialise.m to specify hard-coded parameters and processing options
• Support of Siemens TWIX data format, introducing frequency and phase correction for Siemens users
• Trial support of GSH editing by:
• Dual-channel Spectral registration to accommodate teh water signal being different in OFF and ON scans
• Different fitting priors, limits and model

If you are currently using Gannet, we strongly advise getting this most recent version.  Please continue to feed back to us on bugs and issues that are unclear.

Gannet Quick Start Guide: Again

0.   Get Matlab with Optimisation and Statistics Toolboxes

1.       Get the code from github and add these files to your matlab path

Assuming familiarity with Matlab, make sure all the files downloaded from github are in your matlab path; (i.e.use “add with subfolders”). If you are not familiar with matlab, someone else in your group probably is.

 The Link top left for Gannet 2.0 BETA takes you to github.

2.       What do I type?

Gannet is currently run from two commands – GannetLoad and GannetFit.  This section will cover the load and processing of a single data file. Replace the filename with the actual name of your file.

2.1.    GE data

P files contain a water reference internally, so:

MRS_struct  = GannetLoad({‘GE_data1.7’});

MRS_struct  = GannetFit(MRS_struct);

2.2.    Philips .sdat files

If no water reference data have been collected:

MRS_struct  = GannetLoad({‘Philips1.sdat’});

MRS_struct  = GannetFit(MRS_struct);

If water reference data have been collected:

MRS_struct  = GannetLoad({‘Philips1.sdat’},{‘Philips1_water.sdat’});

MRS_struct  = GannetFit(MRS_struct);

2.3.    Philips .data files

If no water reference data have been collected:

MRS_struct  = GannetLoad({‘Philips1.data’});

MRS_struct  = GannetFit(MRS_struct);

If SEPARATE water reference data have been collected:

MRS_struct  = GannetLoad({‘Philips1.data’},{‘Philips1_water.data’});

MRS_struct  = GannetFit(MRS_struct);

For newer patch versions, the water data is in the same .data file, so use the first option.
MRS_struct  = GannetLoad({‘Philips1.data’});
MRS_struct  = GannetFit(MRS_struct);

2.4.    Siemens .rda files (saved as OFF and ON rda files separately)

MRS_struct  = GannetLoad({'Siemens1_OFF.rda' 'Siemens1_ON.rda'});

MRS_struct  = GannetFit(MRS_struct);
If water reference data have been collected:
MRS_struct  = GannetLoad({ 'Siemens1_OFF.rda' 'Siemens1_ON.rda' },{'Siemens_water.rda'});
MRS_struct  = GannetFit(MRS_struct);

       2.5.   Siemens .dat files (assumes Jamie Near's implementation)
             MRS_struct = GannetLoad({'Siemens1.dat'});
             MRS_struct = GannetFit(MRS_struct);
             If water reference data have been collected:
             MRS_struct = GannetLoad({ 'Siemens1.dat'},{'Siemens1_water.dat'});

             MRS_struct = GannetFit(MRS_struct);


3.       Data Formats

GE, Philips and Siemens data formats are supported. Vendor is chosen according to file endings, so make sure your data files end .7 .rda .sdat or .data.

4.       Assumptions

The formatting of data within the data files is assumed to be the  same as for ‘our’ implementations on Philips and GE, whereas we handle Siemens outputted data that have already been processed into a single data file.  If you are using this software to process your own implementation of GABA-edited MRS, please contact us.

5.       Batch Processing

If you want to batch process files, simply add more that one filename string into the cell arrays, e.g.:

MRS_struct=GannetLoad({'gaba1.dat' 'gaba2.dat'},{'water1.dat' 'water2.dat');