3.5.1

What's changed

• Set figure theme to light for MATLAB R2025a and newer in #51
• Minor bug fixes for MATLAB R2025a in #52

Full changelog: v3.5.0...v3.5.1

3.5.0

New features

• Gannet is now compatible with BIDS
  • bids-matlab, a MATLAB toolkit for interfacing with BIDS datasets, is embedded in Gannet, and users can now input BIDS datasets directly into GannetLoad.m (see documentation for usage instructions)
• Added image QA metrics based on MRIQC
  • GannetSegment.m now calculates and saves the following QA metrics for each anatomical image:
    • Signal-to-noise ratio (SNR) of GM, WM, CSF, and the whole brain (two variants: one using the median absolute deviation of the air background based on Dietrich et al. (2007), and one using the standard deviation of the noise within the tissue class)
    • Contrast-to-noise ratio (CNR) between GM and WM
    • Coefficient of variation (CV) of GM and WM
    • Coefficient of joint variation (CJV) between GM and WM
    • Entropy-focus criterion (EFC)
    • Foreground-background energy ratio (FBER)
    • WM to maximum intensity ratio (WM2MAX): the median intensity within WM over the 95% percentile of the full intensity distribution, that captures the existence of long tails due to hyper-intensity of the carotid vessels and fat
  • These metrics are saved in MRS_struct.out.QA
• Added GitHub Actions for continuous integration with bids-matlab, dicm2nii, and export_fig to ensure compatibility with the latest versions of these dependencies
• Added dependabot.yml to automatically check for updates to GitHub Actions
• Water-unfiltered (but aligned) spectra are now saved in MRS_struct
• All version strings (e.g., MRS_struct.version.*) are now stored under MRS_struct.info.version.*, and datetime stamps for processing steps are added as MRS_struct.info.datetime.*

Major changes

• When calculating GM, WM, and CSF fractions in GannetSegment.m, the probabilistic tissue maps are now thresholded at 0.9 before calculating the fractions. This should improve the accuracy of tissue fraction estimates

Minor changes

• Modified SiemensTWIXRead.m to use iceParam for pointsBeforeEcho in MEGA-sLASER, aligning with MEGA-PRESS handling for consistency
• Changed the naming convention for water residual fit results from ResidWater to resid_water in GannetFit.m for consistency
• Improved input argument validation and error messages, including checks for cell array inputs and file existence, with clearer error output for missing files
• Updated export_fig to v3.52
• Updated dicm2nii to v2025.08.21
• MANY COSMETIC CHANGES to improve code readability and maintainability

Full changelog: v3.4.0...v3.5.0

3.4.0

New features

• Added support for fitting the 2.34 ppm Glu peak in the SUM spectrum
• Added DeIdentifyDisclaimer.m, which prints a disclaimer that the developers provide no guarantee that the de-identification functions will remove all human participants' identifying information in the data header of files
• The RF coil combination used is now stored in MRS_struct.p.RFCoilCombination (note: this only applies to raw data files that are not coil-combined during export from the scanner)
• Data load time (MRS_struct.loadtime) is now stored when GannetLoad.m is run
• Re-added the option to choose the editing pulse order in GannetPreInitialise.m: MRS_struct.p.ON_OFF_order
• MRS voxel masks can now be normalized to MNI152 space; a flag in GannetPreInitiliase.m has been added to do so (note that this is only performed if GannetSegment has been run as the forward deformation map needed for MNI normalization is created during SPM12's segmentation routine)
• Added VoxelMaskOverlap.m, a function that will create a voxel mask that indicates the degree of overlap of all datasets run in a batch
• Added ThreeLorentzModel.m
• Added VoigtModel.m

Minor changes

• An "intro" message is printed whenever GannetLoad.m is run: the version number and a link to the software documentation website is displayed
• Co-registration figure outputs now show the anatomical directions of the displayed MR image (i.e., anterior/posterior [A/P], left/right [L/R], and superior/inferior [S/I])
• Replaced file separators with filesep so that they are specific to users' operating system
• voxoff is now parsed in GERead.m instead of in GannetMask_GE.m and GannetMask_GE_nii.m
• Minor changes to rounding in ExportToCSV.m
• Renamed FitPeaksByFrames2.m to FitPeaksByFrames.m
• Updated export_fig to v3.48
• Updated dicm2nii to v2024.08.21
• MANY COSMETIC CHANGES AND CLEANUP OF OLD UNUSED CODE

Bug fixes

• Updated AlignSubSpectra.m to include Lac and GSH editing
• Updated AlignUsingPeak.m to fit the indexing approach of Gannet 3
• Fixed issue with Siemens .RDA files in CoRegStandAlone.m
• Added MRS_struct.p.seqorig to CoRegStandAlone.m
• Minor fix in GannetMask_NIfTI.m for how voxel offset is parsed from the NIfTI file
• Fixed an issue with GannetFit.m when users choose to fit a specific metabolite
• Corrected a bug in PaperPlot.m for plotting model fits for GABA+Glx
• Fixed an issue in AlignUsingPeak.m when running more than one file in a batch

3.3.2

Major changes

• Rewrote SiemensRead.m to reduce code length

Minor changes

• Updated DICOMRead.m, including to support Siemens XA30 data
• Updated SpectralRegistrationHERMES.m
  • SNR limit is now estimated as in RobustSpectralRegistration.m
  • Bug fix for indexing for output saved from maximum likelihood estimation
• Updated dicm2nii to version 2023.03.16
• Updated export_fig to v3.40
• Added Gannet documentation website URL to error dialog box
• Changed the way path names are printed in error dialog box
• Turned off iteration limit warning in FitChoCr.m
• Updated UpdateGannet.m to ensure all sub-directories are added to the search path after updating
• Added issue templates (in .github/ISSUE_TEMPLATE) for blank issues, bug reports, and feature requests
• Refined alignment of text/logos in output figures
  • The units used for displaying textual results are now normalized to fit to any subplot dimension
  • The textual results in the GannetCoRegister, GannetSegment, CoReg, and Seg output figures are now correctly centered
• The weighted signal averaging method used is now saved in the structure output
• The weighting factors calculated when applying weighted signal averaging are also now saved in the output
• Updated SavePDF.m such that when appending PDFs using export_fig, the figure size will now be equivalent in pixels on Windows and Mac systems
• Updated NIfTIMRSRead.m
• Updated README.md
• Updated GannetFitPhantom.m
• Removed redundant global frequency shift in RobustSpectralRegistration.m
• The z-standardized MSEs calculated in the spectral registration subroutines are now saved in the structure output
• Updated GannetVersion.m to also output version numbers of Gannet modules
• A warning is now printed when users process Siemens .rda data encouraging them to instead use TWIX (.dat) data
• Added support for GE P-file header revision 30 (#28)
• MANY COSMETIC CHANGES

Bug fixes

• Bug fix for special character \ in Windows file path names printed in the error dialog box
• Fixed bug in GannetMask_NIfTI.m where the co-registered MRS voxel was incorrectly flipped in the GannetCoRegister output figure
• Fixed bug in GannetQuantify.m where the alpha value was incorrectly being printed multiple times when multiple were run in batch
• Added fix in VersionCheck.m so that when users have limited or restricted internet access, an error is avoided (#27) - thanks @alexcraven!

3.3.1

New features

• Compressed NIfTI files (*.nii.gz) are now fully supported
• Gannet now fully quantifies metabolite levels for Cr, Cho, and NAA (estimated from the OFF
  spectrum)

Major changes

• Moved local signal model functions out of GannetFit.m and into their own files:
  • BaselineModel.m
  • CalcIU.m
  • DoubleGaussModel.m
  • EtOHModel.m
  • GABAGlxModel.m
  • GaussModel.m
  • LorentzGaussModel.m
  • LorentzGaussModelP.m
• Added GetFullPath.m; Gannet now will find the full path of input files by default
• Renamed some of the data-loading functions

Minor changes

• Added a check in GannetQuantify.m for datasets without water references; GannetQuantify.m will
  not run if no water references are present
• Added a check in GannetCoRegister.m to ensure all structural image files can be found
• Updated export_fig to v3.33
• Updated dicm2nii to version 2023.03.08
• Updated LICENSE and README.md
• Updated ExportToCSV.m
• Updated CoRegStandAlone functions
• Replaced use of 1i with complex()
• Removed unused variable T1max
• Removed unnecessary ones() parameter in LorentzModel.m and TwoLorentzModel.m
• Philips *.spar file extension is no longer saved in the output structure
• Removed calculation of df in GannetLoad.m; added dt in its place
• Exported CSV files will no longer be overwritten if a CSV file of the same name already exists in
  the output directory; instead, a new file is created and appended with an integer
• Added new output structure attribute nrows_water
• Reordered structure subfields for metabolites in GannetFit.m and ExportToCSV.m
• Shifted Gannet logo and version number in PDF outputs slightly to the right
• Alpha values are now included in exported CSV files
• Replaced the Gannet logo with a PNG version
• MANY COSMETIC CHANGES

Bug fixes

• Added a check for letter case of *.dcm and *.ima files in DICOMRead.m and SiemensDICOMRead.m
  (dir() is case-sensitive in Linux)
• Added a fix to avoid an error where MATLAB tried to close figures following an unrelated internal
  error, but no figures were created
• Fixed a bug in NIfTIMRSRead.m that led to an error if the Manufacturer field is not found in
  the data file header
• If export_fig.m cannot be found on the search path and append has been flagged in
  GannetPreInitialise.m, it is made clear to the user that PDFs will be saved separately
• Fixed bugs in AlignUsingH2O.m
• Fixed a bug in SiemensDICOMRead.m where an error occurred if centerFreq is not found in the
  data file header

3.3.0

New features

• Added functionality to read NIfTI-MRS files (Clarke et al., MRM, 2022) (NIfTIMRSRead.m); includes additional new function GannetMask_NIfTI.m for voxel co-registration
• Added support for Utah Siemens MEGA-PRESS sequence (DICOM files)
• Added support for CMRR PRESS data (DICOM files)
• Added support for Siemens XA30 sequence as provided by JHU
• Changed README to README.md, which now includes badges

Major changes

• Coil combination of GE, NIfTI-MRS, and Siemens TWIX files is now performed using generalized least squares (An et al., JMRI, 2013); this approach has been shown to result in optimal SNR and reduce spectral artifacts
• The Gannet logo has been reverted to the original image of a gannet

Minor changes

• Added functionality for GE data in AlignSubSpectra_PreAlignRef.m
• An error is presented if not enough inputs are given for any of the Gannet modules
• CoRegStandAlone outputs can be hidden if MRS_struct.p.hide is set to 1 in CoRegStandAlone.m (default is 0)
• If the user has no internet connection, VersionCheck.m and UpdateGannet.m will not run
• Updated dicm2nii to latest version (version 2022.09.15)
• Updated mapVBVD functions to latest version (https://github.com/pehses/mapVBVD)
• Turned off warnings of iteration limits in SpectralRegistrationHERMES.m and GannetFit.m
• Many cosmetic changes in the code

Bug fixes

• Fixed bug in error reporting in GannetFit.m
• CoRegStandAlone routines now parse version numbers from the main modules properly
• Variable filesExist in GannetSegment.m may not populate; it is now pre-initialized as a precaution
• Bug fix in GannetMask_SiemensRDA.m
• Bug fixes for reading DICOM files

3.2.1

Minor changes

• PhaseCorrection.m now deals better with spectra that have a non-zero baseline
• SPM12 now outputs a forward deformation field (needed for normalizing voxel masks to MNI space)
• Updated export_fig to v3.27
• CoRegStandAlone.m now exports a CSV file
• Various cosmetic changes

Bug fixes

• Fixed sub-spectra alignment for GE HERCULES data
• Fixed bug in CoRegStandAlone.m
• Fixed bug in read_dcm_header.m (thanks to Meredith Reid)

3.2.0

New features

• Added GannetVersion.m, VersionCheck.m, and UpdateGannet.m; these new functions let users know the version of Gannet they have, if a newer release of Gannet is available, and will allow them to automatically update if wanted
• Added ToolboxCheck.m to check for missing MATLAB toolboxes needed to run Gannet
• Error dialog boxes are displayed at the end of the analysis pipeline if an error occurred (during a batch analysis, Gannet will skip to the next dataset and continue running)
• Users can now choose to use weighted (the default) or conventional signal averaging in GannetPreInitialise.m (outlier scans are removed when using conventional averaging, as before)
• Added a new (optional) method for robust, weighted signal averaging: weighted averaging by criterion function minimization (WACFM) using the generalized Cauchy distribution as the cost function; see doi: 10.1016/j.bbe.2015.06.002 for more details; additionally, instead of weighting difference pairs, the subspectra of each editing subexperiment are weighted to generate weighted subspectra, which are then subtracted; see SignalAveraging.m
• Yair Altman's export_fig toolbox is included as an optional toolbox that, if added to MATLAB's search path, Gannet will use to append all output PDFs from each module into a single PDF (a flag must be set in GannetPreInitialise.m to do this); this is very useful for easy QA of lots of data; note that Ghostscript needs to be installed for the appending of PDFs to work (NB: macOS users should use this version or use Homebrew to install Ghostscript)
• Implemented use of hyperlinks in info and error messages printed in the command window so that users can: (1) directly run a certain function (such as UpdateGannet.m when VersionCheck.m informs the user a new release is available); (2) go straight to the line of code where an encountered error can be fixed (such as errors in GannetPreInitialise.m); or (3) go to a website by clicking on the printed URL (such as to download SPM12); the relevant code has been borrowed from export_fig
• Added an option in GannetPreInitialise.m that allows users, when using robust spectral registration, to use the averaged pre-aligned subspectra as references for aligning the averaged post-aligned subspectra (this may be helpful when robust spectral registration makes the alignment of already good-quality pre-aligned spectra worse)
• PaperPlot.m now allows users to plot an exemplary voxel mask co-registered to the respective structural image
• Added GannetMask_GE_nii.m; GE users can now use NIfTI images instead of DICOMs to co-register their MRS voxels to structural images
• Added the ability to trim datasets
• Extended the ability to concatenate files, including over multiple subjects
• Added a flag in GannetPreInitialise.m (MRS_struct.p.hide) to prevent output figures from displaying (useful when processing a large batch of files)

Major changes

• The outdated manual PDF has been removed; up-to-date software documentation will now be found online: https://markmikkelsen.github.io/Gannet-docs/index.html
• Gannet is now licensed under the BSD 3-Clause License
• Alpha tissue correction is now performed on a by-metabolite basis rather than fixing the intrinsic WM:GM concentration to 1:2 (alpha) for all metabolites (assuming for now the ratio is 1:2 for GABA and Glx and 1:1 for GSH, EtOH and Lac); the alpha that is assumed is displayed in the GannetQuantify output figure
• Removed MRS_struct.p.ON_OFF_order from GannetPreInitialise.m; the order of editing pulses is now determined automatically; the relevant code has been borrowed from Osprey (this has only been tested to a limited extent so may require further tweaking)
  • The exception to this change is phantom data, where users will still need to specify the order of editing pulses

Minor changes

• Datasets with differing number of averages can now be batch-processed together
• Turned off the progress bar displayed when loading Siemens TWIX data to reduce loading time
• Renamed some files for the sake of clarity and style; removed obsolete GannetMask.m
• Signal averaging and subtraction are now done in the new function SignalAveraging.m
• Various improvements to RobustSpectralRegistration.m (formerly Robust_Spectral_Registration.m) for better handling of data acquired using very strong water suppression
• The assumed concentration of pure water in GannetFit.m and GannetFitPhantom.m (PureWaterConc) has been changed from 55 to 55.51 mol/kg; this puts it in line with the same constant used in GannetQuantify.m
• Added edits from Ralph Noeske (GE Berlin) to GERead.m for better handling of data when nechoes == 1; also changed the scaling factor if nechoes > 1 (hopefully this makes water-referenced measurements consistent across all data encoding flavors)
• In GERead.m and PhilipsRead_data.m, instead of using the first point in the FID for signal weighting, the most common point that is the max in the magnitude signal across all FIDs is now used
• Some changes to SiemensDICOMRead.m and DICOMRead.m for smarter handling of data files: for each dataset, metabolite and water data files should be stored in separate folders
• Improved ExportToCSV.m; a single .csv file is now exported for HERMES datasets; useful variables such as signal areas and Cr fit quality metrics are now also exported
• Rewrote DiscernDataType.m (formerly GannetDiscernDatatype.m)
• Minor changes and improvements to PaperPlot.m
• Minor changes to CoRegStandAlone.m functions
• Minor changes to SignalFilter.m
• Simplified EddyCurrentCorrection.m (formerly phase_correction_fids.m)
• Set up SPM12 for batch tissue segmentation only when tissue segmentation has not already been run and do it only once in a batch
• AllFramesFT (for the last loaded dataset) is now also saved in MRS_struct.spec
• When saving the MRS_struct structure, the .mat file is now saved using version 7.3 (for the rare case when the structure is >= 2 GB on 64-bit computers)
• Removed MRS_struct.p.sdat from GannetPreInitialise.m and the corresponding code from GannetLoad.m (this feature was never really used by users afaik)
• Improved global zero-order phasing in SpectralRegistrationHERMES.m
• Many cosmetic/aesthetic changes
  • The module output figures now show information useful for reporting acquisition parameters and results (in line with the MRSinMRS checklist)
  • Co-registered/segmented voxel masks displayed in GannetCoRegister, GannetSegment, and GannetQuantify output figures are now shown in yellow rather than grayscale
  • Smarter stacking of HERMES difference spectra in PlotPrePostAlign.m and PlotPrePostAlign2.m (formerly GannetPlotPrePostAlign.m and GannetPlotPrePostAlign2.m)
  • The Gannet documentation website URL is printed at the bottom of every output figure
  • Removed irrelevant messages from being printed in the command window during the analysis pipeline, replacing them with more useful messages
  • Minor rearranging of results text in GannetSegment and GannetQuantify output figures
  • Slight change to the y-axis labels of the Cr frequency spectrogram in the GannetLoad output figure
  • Better reordering of MRS_struct.out subfields created in GannetFit.m

Bug fixes

• Frequency and phase offset estimates are now tracked correctly and saved when running any of the spectral registration-based alignment methods
• Removed old debugging conditional statement in TWIXDeIdentify.m
• Explicitly specify color of water frequency trace in GannetLoad output figure as there appears to be a bug since MATLAB R2019b when using hold to overlay plots
• Added EtOH signal parameters to GannetQuantify.m
• In SiemensTwixRead.m, if no water reference is provided, use the most common point that is the max in the magnitude signal across all FIDs instead of just using the first point
• Fixed an orientation problem in GannetMask_GE.m
• Removed unnecessary complex conjugate transpose during FFT of water data in GannetLoad.m
• Turned off warnings about legacy number generator in RobustSpectralRegistration.m (for when rng and randn are run in SignalFilter.m) if they are already turned on