GannetMask and GannetSegment

These new functions are still a work in progress, but by way of documentation for anyone brave enough to try, here is the gist of things.

 MRS_struct  = GannetLoad({'gabafile.SDAT'},{'waterfile.SDAT'});
 MRS_struct  = GannetFit(MRS_struct);
 MRS_struct=GannetMask_Philips('gabafile.SPAR','T1.nii',MRS_struct,1);
 MRS_struct =  GannetSegment(MRS_struct);

 

Frequency Stabilization

Edit 9/14/2015: This post is superceded by today's post.

We have written a couple of papers on subtraction artefacts (Evans et al. JMRI 2013) and field drift (Harris et al. MRM 2014).  Obviously as a subtraction technique, stability is important for MEGA-PRESS.  However, one aspect that we have not emphasised is the impact of drift on editing efficiency. As the field drifts, the offset of editing pulses moves from their intended target and the editing efficiency of GABA (and MM) changes.  This is especially important for MM-suppressed editing, where small drifts can rapidly lead to positive or negative MM signals bleeding back in.  MM suppression relies upon editing pulses that are symmetrically disposed about the MM signal to properly null MM.  This symmetry is destroyed by the field drift that occurs due to scanner heating/cooling and subject movement.

The Philips scanner has a Frequency Stabilization (FS) function programmed in. Basically, it performs a whole-slice gradient echo measurement to determine changes in the offset. This quick, small-flip-angle water measurement, which is interleaved within the TR, is strongly recommended not to be used for proton spectroscopy, largely because it is inaccurate.  In the new patches for releases 5.1.2, 6.1.7 and 5.1.8, we have added a buffer-averaging feature to this stabilization.  Offset updates are based not on a single FS measurement, but on the average of the previous n measurements (where n is set by the parameter Frequency Stabilization window, which appears when FS is turned ON).  The idea being that the original implementation's main failing is that it is noisy, and averaging helps address that.  In a way MEGA-PRESS is the ideal application for an averaged approach, since we do not want to update the frequency every TR.  This approach seems to be beneficial, but is still being investigated.  If you would like to apply it in your experiments, some suggested parameters are given below.

Strengths

• In the presence of moderate instability, MM suppression is improved by locking the frequency.

• This method is more accurate than the Philips standard FS (which can still be used by changing the window to 1).

• The FS feature can turn off without warning (although possibly less now that the averaging removes spikes).

• This is largely untested.

• The averaged window approach tends to lag behind in the case of drift, and respond more slowly in the case of sudden movement.

Weaknesses

Parameters

Frequency Stabilization: yes (in the motion tab)

Frequency Stab window: 16 (same tab). This is a trade-off between averaging benefit and lag...

+freq stab odd dyn: yes (in the dyn/ang tab). This makes sure the frequency only updates on the first TR of an odd dynamic scan, helping minimize subtraction artefacts.

Piperidate

For anyone that finds it irritating to spell out GABA in papers, why not use the old-school piperidate instead?  Maybe it'll catch on.

GannetCoRegister Outputs

GannetCoRegister is up-and-running for GE and Philips datasets.  Voxel placements seem to agree with screenshots of the prescription, and further comment from testing elsewhere is welcomed.  The new workflow runs: GannetLoad; GannetCoRegister; GannetFit.  Each of the three modules saves a pdf output - GannetCoRegister's reports the voxel location and geometrical parameters.

One frame of the 3-plane output is now also incorporated into the GannetFit output.

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.