Hello, I am new to processing MRS data and Osprey but found the tool very easy to use and really appreciate all of the work on it!

I recently pushed a dataset through Osprey and am interested in GABA quantification. I know from the HERMES methods paper that to quantify GABA I should take the differences between the sum of the spectra with GABA “ON” and the sum of the spectra with GABA “OFF”. There are three outputs from quantification that are called “diff1”, “diff2”, and “sum”. I was wondering which of these to use? Any help is appreciated.

Also as a side note, even though I set my sequence to HERMES in my configuration file, I still see “HERCULES” at the top of the GUI for the sequence type. I am not sure why.

Hi @Claar727,

Nice to have you here, thanks for reaching out.

diff1 is the GABA-edited spectrum. You will need to calculate GABA+, i.e., the combined amplitude from GABA and the co-edited macromolecular signal (this will depend on the co-edited MM parametrization method that you have used in the job file).

(Not sure why it says HERCULES. Can you confirm that it is called HERMES and not HERCULES in your exam card?)


Thanks for your quick reply!

So I would add the GABA column in the tsv output from quantify step to the other MM columns to get the GABA+ concentration?

And I just checked our card and it has the sequence labeled as “HERMES_GABA_GSH_EtOH” and whenever I look at the header of the twix data using the twixtools package I see the name of the sequence is svs_hermes so I’m not sure why HERCULES would come up.

Not to all the other MM columns. You need to identify the MM basis function that contributes to the 3-ppm co-edited signal in the GABA-edited difference spectrum.

About the sequence name - which software version are you using and what exam card settings? You’re measuring ethanol then?

Sorry for the delayed reply!

Also sorry that the message is so long. I am a new user so I can’t embed more than one media item.

I will go ahead and try to figure out what the MM basis function is. I chose the default set of metabolites in my job file (below) so I would assume I would just use those metabolites.

%% jobSDAT.m
%   This function describes an Osprey job defined in a MATLAB script.
%   A valid Osprey job contains four distinct classes of items:
%       1. basic information on the MRS sequence used
%       2. several settings for data handling and modeling
%       3. a list of MRS (and, optionally, structural imaging) data files
%          to be loaded
%       4. an output folder to store the results and exported files
%   The list of MRS and structural imaging files is provided in the form of
%   cell arrays. They can simply be provided explicitly, or from a more
%   complex script that automatically determines file names from a given
%   folder structure.
%   Osprey distinguishes between four sets of data:
%       - metabolite (water-suppressed) data
%           (MANDATORY)
%           Defined in cell array "files"
%       - water reference data acquired with the SAME sequence as the
%           metabolite data, just without water suppression RF pulses. This
%           data is used to determine complex coil combination
%           coefficients, and perform eddy current correction.
%           (OPTIONAL)
%           Defined in cell array "files_ref"
%       - additional water data used for water-scaled quantification,
%           usually from short-TE acquisitions due to reduced T2-weighting
%           (OPTIONAL)
%           Defined in cell array "files_w"
%       - Structural image data used for co-registration and tissue class
%           segmentation (usually a T1 MPRAGE). These files need to be
%           provided in the NIfTI format (*.nii or *.nii.gz) or, for GE data, as a
%           folder containing DICOM Files (*.dcm).
%           (OPTIONAL)
%           Defined in cell array "files_nii"
%       - External segmentation results. These files need to be
%           provided in the NIfTI format (*.nii or *.nii.gz).
%           (OPTIONAL)
%           Defined in cell array "files_seg" with 1 x 3 cell for each
%           subject or 1 x 1 cell if a single 4D NIfTI is supplied.
%   Files in the formats
%       - .7 (GE)
%       - .SDAT, .DATA/.LIST, .RAW/.SIN/.LAB (Philips)
%       - .DAT (Siemens)
%       - .nii, .nii.gz (NIfTI-MRS)
%   usually contain all of the acquired data in a single file per scan. GE
%   systems store water reference data in the same .7 file, so there is no
%   need to specify it separately under files_ref.
%   Files in the formats
%       - .DCM (any)
%       - .IMA, .RDA (Siemens)
%   may contain separate files for each average. Instead of providing
%   individual file names, please specify folders. Metabolite data, water
%   reference data, and water data need to be located in separate folders.
%   In the example script at hand the MATLAB functions strrep and which are
%   used to generate a relative path, which allows you to run the examples
%   on your machine directly. To set up your own Osprey job supply the
%   specific locations as described above.
%       Dr. Georg Oeltzschner (Johns Hopkins University, 2019-07-15)
%       2019-07-15: First version of the code.


% Specify sequence type
seqType = 'HERMES';           % OPTIONS:    - 'unedited' (default)
                                %             - 'MEGA'
                                %             - 'HERMES'
                                %             - 'HERCULES'

% Specify editing targets
editTarget = {'GABA', 'GSH'};           % OPTIONS:    - {'none'} (default if 'unedited')
                                %             - {'GABA'}, {'GSH'}, {'Lac'}, {'PE322'}, {'PE398'}  (for 'MEGA')
                                %             - {'GABA', 'GSH'}, {'GABA', 'Lac'}, {'NAA', 'NAAG'} (for 'HERMES'and 'HERCULES')

                                % Specify data scenario
dataScenario = 'invivo';        % OPTIONS:    - 'invivo' (default)
                                %             - 'phantom'
                                %             - 'PRIAM'
                                %             - 'MRSI'

% Which spectral registration method should be used? Robust spectral
% registration is default, a frequency restricted spectral registration
% method is also availaible and is linked to the fit range.
opts.SpecReg = 'RobSpecReg';                  % OPTIONS:    - 'RobSpecReg' (default) Spectral aligment with Water/Lipid removal, using simialrity meric, and weighted averaging
                                              %             - 'ProbSpecReg' Probabilistic spectral aligment to median target and weighted averaging
                                              %             - 'RestrSpecReg' Frequency restricted (fit range) spectral aligment, using simialrity meric, and weighted averaging
                                              %             - 'none'

% Which algorithm do you want to align the sub spectra? L2 norm
% optimization is the default. This is only used for edited MRS!
%Perform correction on the metabolite data (raw) or metabolite
%-nulled data (mm).
opts.SubSpecAlignment.mets = 'L2Norm';          % OPTIONS:    - 'L2Norm' (default)
                                                %             - 'L1Norm'
                                                %             - 'none'

%Perform eddy-current correction on the metabolite data (raw) or metabolite
%-nulled data (mm). This can either be done similar for all data sets by
%supplying a single value or specified for each dataset individually by supplying
% multiple entries (number has to match the number of datasets) e.g. to perform ECC
% for the second dataset only:
% opts.ECC.raw              = [0 1];
%               = [0 1];

opts.ECC.raw                = 1;                % OPTIONS:    - '1' (default)                 = 1;                %             - '0' (no)
                                                %             - [] array

% Save LCModel-exportable files for each spectrum?
opts.saveLCM                = 0;                % OPTIONS:    - 0 (no, default)
                                                %             - 1 (yes)
% Save jMRUI-exportable files for each spectrum?
opts.savejMRUI              = 0;                % OPTIONS:    - 0 (no, default)
                                                %             - 1 (yes)

% Save processed spectra in vendor-specific format (SDAT/SPAR, RDA, P)?
opts.saveVendor             = 0;                % OPTIONS:    - 0 (no, default)
                                                %             - 1 (yes)

% Save processed spectra in NIfTI-MRS format?
opts.saveNII                = 0;                % OPTIONS:    - 0 (no)
                                                %             - 1 (yes, default)

% Save PDF output for all Osprey modules and subjects?
opts.savePDF                = 0;                % OPTIONS:    - 0 (no, default)
                                                %             - 1 (yes)

% Save mat file of the compiled fitting parameters?
opts.exportParams.flag      = 0;                % Options:    - 0 (no, default)
                                                %             - 1 (yes)
opts.exportParams.path      = '';               % Replace with string for the path 
                                                % to the save directory

% Select the metabolites to be included in the basis set as a cell array,
% with entries separates by commas.
% With default Osprey basis sets, you can select the following metabolites:
% Ala, Asc, Asp, bHB, bHG, Cit, Cr, Cystat, CrCH2, EtOH, GABA, GPC, GSH, Glc, Gln,
% Glu, Gly, H2O, mI, Lac, NAA, NAAG, PCh, PCr, PE, Phenyl, sI, Ser,
% Tau, Tyros, MM09, MM12, MM14, MM17, MM20, Lip09, Lip13, Lip20.
% If you enter 'default', the basis set will include all of the above
% except for Ala, bHB, bHG, Cit, Cystat, EtOH, Glc, Gly, Phenyl, Ser, and Tyros.      = {'default'};      % OPTIONS:    - {'default'}
                                                %             - {custom}

% Choose the fitting algorithm             = 'Osprey';         % OPTIONS:    - 'Osprey' (default)
                                                %             - 'LCModel'

% Choose the fitting style for difference-edited datasets (MEGA, HERMES, HERCULES)
% (only available for the Osprey fitting method)              = 'Separate';       % OPTIONS:    - 'Concatenated' (default) - will fit DIFF and SUM simultaneously)
                                                %             - 'Separate' - will fit DIFF and OFF separately

% Determine fitting range (in ppm) for the metabolite and water spectra              = [0.5 4];          % [ppm] Default: [0.5 4]         = [2.0 7.4];        % [ppm] Default: [2.0 7.4]

% Determine the baseline knot spacing (in ppm) for the metabolite spectra     = 0.4;              % [ppm] Default: 0.4.

% Add macromolecule and lipid basis functions to the fit?              = 1;                % OPTIONS:    - 0 (no)
                                                %             - 1 (yes, default)
% Optional: In case the automatic basisset picker is not working you can manually
% select the path to the basis set in the osprey/fit/basis, i.e.:
% = 'osprey/fit/basis/3T/philips/mega/press/gaba68/basis_philips_megapress_gaba68.mat';

% Optional: Deface the strucutral images in the Coreg/Seg figures for HIPAA
% compliance 
opts.img.deface             = 1;

% When using single-average Siemens RDA or DICOM files, specify their
% folders instead of single files!

% Clear existing files
clear files files_ref files_w files_nii files_mm

% Data folder in BIDS format
% The filparts(which()) comment is needed to find the data on your machine. If you set
% up the jobFile for your own data you can set a direct path to your data
% folder e.g., data_folder = /Volumes/MyProject/data/'

data_folder = '/blue/vabfmc/data/archive/Lamb_BT/';
t1_folder = fullfile('/blue/vabfmc/data/working/robert727/cda2/data_processing/data/mrs/osprey/t1w/');

% Adding this section to capture the correct files
metab_file_format = '_acq-hermes_nuc-1H_vox-rtinsula_svs.dat';
ref_file_format = '_acq-hermes_nuc-1H_type-ref_vox-rtinsula_svs.dat';

% The following lines perform an automated set-up of the jobFile which
% takes advatage of the BIDS foramt. If you are not using BIDS (highly
% recommended) you can look at the definitions below the loop to see how to
% set up direct path links to your data.

subs       = dir(data_folder);
subs(1:2)  = [];
subs       = subs([subs.isdir]);
subs       = subs(contains({},'sub'));
counter    = 1;

% Loop over subjects
for kk = 1:length(subs)

    % Specify metabolite, reference, and T1 file paths for this subject
    metab_file = fullfile(data_folder, subs(kk).name, 'mrs', strcat(subs(kk).name, metab_file_format));
    ref_file = fullfile(data_folder, subs(kk).name, 'mrs', strcat(subs(kk).name, ref_file_format));
    t1_file = fullfile(t1_folder, strcat(subs(kk).name, '_T1w.nii'));

    % Check if metabolite, reference, and T1 files exist
    if isfile(metab_file) && isfile(ref_file) && isfile(t1_file)

        % If they do exist, sometimes small, extra dat files are created
        % check if out metab and ref files are of the right size
        metab_file_size = dir(metab_file).bytes / 1e6;
        ref_file_size = dir(ref_file).bytes / 1e6;
        % If metab file is of the proper size, add it to our files
        % list. Else don't.
        if metab_file_size >= 250
            include_metab = true;
            include_metab = false;

        % Do the same for the reference file
        if ref_file_size >= 30
            include_ref = true;
            include_ref = false;
        % If both metab and ref file are of appropriate size. Add files to
        % file arrays
        if include_ref && include_metab
            files(counter)      = {[fullfile(data_folder, subs(kk).name, 'mrs', strcat(subs(kk).name, metab_file_format))]};
            files_ref(counter)  = {[fullfile(data_folder, subs(kk).name, 'mrs', strcat(subs(kk).name, ref_file_format))]};
            files_nii(counter)  = {[fullfile(t1_folder, strcat(subs(kk).name, '_T1w.nii'))]};
            counter             = counter + 1;

    % Specify water data for quantification (e.g. short-TE water scan)
    % (OPTIONAL)
    files_w     = {};

    % Specify metabolite-nulled data for quantification
    % (OPTIONAL)
    files_mm     = {};

    % External segmentation results
    % (OPTIONAL)
    % Link to NIfTI (*.nii or *.nii.gz) files with segmentation results
    % Add supply gray matter, white matter, and CSF as 1 x 3 cell within a
    % cell array  or a single 4D file in the same order supplied as 1 x 1 cell;
    %         files_seg(counter)   = {{[sess(ll).folder filesep sess(ll).name filesep 'anat' filesep subs(kk).name filesep 'c1' sess(ll).name '_T1w.nii.gz'],...
    %                                  [sess(ll).folder filesep sess(ll).name filesep 'anat' filesep subs(kk).name filesep 'c2' sess(ll).name '_T1w.nii.gz'],...
    %                                  [sess(ll).folder filesep sess(ll).name filesep 'anat' filesep subs(kk).name filesep 'c3' sess(ll).name '_T1w.nii.gz']}};

    %         files_seg(counter)   = {{[sess(ll).folder filesep sess(ll).name filesep 'anat' filesep subs(kk).name filesep '4D' sess(ll).name '_T1w.nii.gz']}};


% Definitions without using BIDS

% You can always supply direct path to each of the files within
% the cell array. For example:

% Specify metabolite data
% files(counter)      = {'/Volumes/MyProject/data/sub-01/mrs/PRESS_act.SDAT',...
%                        '/Volumes/MyProject/data/sub-02/mrs/PRESS_act.SDAT'};

% Specify water reference data for eddy-current correction (same sequence as metabolite data!)
% Leave empty for GE P-files (.7) - these include water reference data by
% default.
% files_ref(counter)      = {'/Volumes/MyProject/data/sub-01/mrs/PRESS_ref.SDAT',...
%                            '/Volumes/MyProject/data/sub-02/mrs/PRESS_ref.SDAT'};

% Specify water data for quantification (e.g. short-TE water scan)
% files_w     = {};

% Specify metabolite-nulled data for quantification
% files_mm     = {};

% Specify T1-weighted structural imaging data
% Link to single NIfTI (*.nii.gz or #.nii) files for GE, Siemens and Philips data
% files_nii  = {'/Volumes/MyProject/data/sub-01/anat/T1w.nii.gz',...
%               '/Volumes/MyProject/data/sub-02/anat/T1w.nii.gz'};

% External segmentation results
% Link to NIfTI (*.nii or *.nii.gz) files with segmentation results
% Add supply gray matter, white matter, and CSF as 1 x 3 cell within a
% cell array  or a single 4D file in the same order supplied as 1 x 1 cell;
%         files_seg(counter)   = {{'/Volumes/MyProject/data/sub-01/anat/c1T1w.nii.gz',...
%                                  '/Volumes/MyProject/data/sub-01/anat/c2T1w.nii.gz',...
%                                  '/Volumes/MyProject/data/sub-01/anat/c3T1w.nii.gz'},...
%                                   {'/Volumes/MyProject/data/sub-02/anat/c1T1w.nii.gz',...
%                                  '/Volumes/MyProject/data/sub-02/anat/c2T1w.nii.gz',...
%                                  '/Volumes/MyProject/data/sub-02/anat/c3T1w.nii.gz'}};
%         files_seg(counter)   = {{'/Volumes/MyProject/data/sub-01/anat/4DT1w.nii.gz'},...
%                                   {'/Volumes/MyProject/data/sub-02/anat/4DT1w.nii.gz'}};

% Supply location of a csv file, which contains possible correlation
% measures and group variables. Each column must start with the name of the
% measure. For the grouping variable use 'group' and numbers between 1 and
% the number of included groups. If no group is supplied the data will be
% treated as one group. (You can always use the direct path)
osprey_config_path = fullfile("/blue", "vabfmc", "data", "working", "robert727", "cda2", "data_processing", "data", "mrs", "osprey", "config");
% file_stat = fullfile(osprey_config_path, 'rtinsula_stats.csv');

% The Osprey data container will be saved as a *.mat file in the output
% folder that you specify below. In addition, any exported files (for use
% with jMRUI, TARQUIN, or LCModel) will be saved in sub-folders.

% Specify output folder (you can always use the direct path)
outputFolder = fullfile('/blue', 'vabfmc', 'data', 'working', 'robert727', 'cda2', 'data_processing', 'results', 'mrs', 'osprey', 'rtinsula_outputs');


Based on the naming of the editing sequence (HERMES_GABA_GSH_EtOH) and that there are 3 editing pulses, I would assume we are measuring ethanol. After looking more closely at the job file, I see that EtOH is not included in the default basis set so I would likely want to include it in addition to the default options. However, it doesn’t look like

editTarget = {'GABA', 'GSH', 'EtOH'}

is an option so maybe using Osprey is not valid for our sequence?

You’ll notice some extra code in the job file (above) that checks that files exist and that the metabolite and reference files are of the appropriate size. I’m not sure if other Siemens scanners do this, but ours will randomly (at least we haven’t been able to determine a pattern) generate small, extra dat files that accidentally get labeled as the main dat file in our BIDS data ingestion/organization process so my code checks that the files are of the appropriate size.

I am still new to analyzing MRS data so there is a high chance I am missing some fundamental knowledge here. If you could recommend any reading/resources to get a better understanding of this, that would be greatly appreciated.

I have attached the relevant portions of our exam card as a PDF.

Our Siemens scanner software information is:

  • Series Number: 166017
  • Software: NUMARIS/4
  • Version: syngo MR E11 DHHS
  • Siemens Software Packages:
    • COEM VZ10F_SL02P02
    • syngo VH22B_SL19P26_CSI03
    • N4_VE11C_LATEST_20160120
    • N4_VE11C_LATEST_20160120_P16 (SP01)
    • N4_VE11C_FEATURE_20160120_SD04_F1 (SD04)

I am using Osprey version 2.5.0. I tried to attach a screenshot from the Osprey GUI I am using to analyze our frontal voxel data, but can only attach one item. The GUI is displaying HERCULES as the sequence type despite HERMES being included everywhere else in my data and in the exam card.

Thanks for your help and let me know if there is any other information I can provide!

exam_card.pdf (130.7 KB)

Hi @Claar727,

Actually {‘GABA’,‘GSH’,‘EtOH’} is a valid option for the edit target it just hasn’t made it into the options list. You can go ahead and change it.

You are right that EtOH is not part of the default basis set list. So what you can do is add a manual list like this in the jobfile:      ={'Asc','Asp','Cr','CrCH2','EtOH', ...
                     ,'GABA','GPC','GSH','Gln','Glu' ...
                     ,'Ins','Lac','NAA','NAAG','PCh','PCr','PE' ...

The reason for Osprey defining the sequence as HERCULES is due to the lack of information in the header of the twix file. This is not a problem during the analysis as long as you correctly update the editTarget and the seqType in the jobfile. Osprey comes with the correct Siemens HERMES GABA-GSH-EtOH basis set.

Lastly, I agree with you that from what I can see in the exam card you ran a GABA-GSH-EtOH experiment. Can you try running the analysis with the updated settings and see if you get an EtOH difference spectrum?

I have also attached a json jobfile that I have used during the implementation. You just have to change the extension back to .json so that you can use it as input jobfile.


jobHERMES-EtOH.txt (1.0 KB)

Thanks! I will go ahead and re-run my analyses this week and let you know how it goes.


I have edited my job file (attached) to include EtOH as a target and manually entered the basis set elements to include EtOH and now I am getting an error. I am not sure if it is related or not.

I did not use the job file you sent me, but rather changed my job file to match the one you attached besides the data directories, output directories, etc.

Timestamp October 17, 2023 14:24:53 Osprey 2.5.0  OspreyGUI
Timestamp October 17, 2023 14:28:28 Osprey 2.5.0  OspreyProcess
Processing data from dataset   1 out of 111 total datasets...
{Unrecognized function or variable 'outA'.

Error in <a href="matlab:matlab.internal.language.introspective.errorDocCallback('osp_editSubSpecAlign', '/blue/vabfmc/data/working/robert727/software/osprey/process/osp_editSubSpecAlign.m', 304)" style="font-weight:bold">osp_editSubSpecAlign</a> (<a href="matlab: opentoline('/blue/vabfmc/data/working/robert727/software/osprey/process/osp_editSubSpecAlign.m',304,0)">line 304</a>)
    out = op_mergesubspec(outA,outB,outC,outD);

Error in <a href="matlab:matlab.internal.language.introspective.errorDocCallback('OspreyProcess', '/blue/vabfmc/data/working/robert727/software/osprey/process/OspreyProcess.m', 625)" style="font-weight:bold">OspreyProcess</a> (<a href="matlab: opentoline('/blue/vabfmc/data/working/robert727/software/osprey/process/OspreyProcess.m',625,0)">line 625</a>)
                                [raw]  = osp_editSubSpecAlign(raw, seq, target1,target3,MRSCont.opts.UnstableWater);

Error in <a href="matlab:matlab.internal.language.introspective.errorDocCallback('osp_onProc', '/blue/vabfmc/data/working/robert727/software/osprey/GUI/osp_onProc.m', 37)" style="font-weight:bold">osp_onProc</a> (<a href="matlab: opentoline('/blue/vabfmc/data/working/robert727/software/osprey/GUI/osp_onProc.m',37,0)">line 37</a>)
    MRSCont = OspreyProcess(MRSCont);
Error while evaluating UIControl Callback.

matlab.internal.language.introspective.errorDocCallback('osp_editSubSpecAlign', '/blue/vabfmc/data/working/robert727/software/osprey/process/osp_editSubSpecAlign.m', 304)
Timestamp October 17, 2023 15:36:33 Osprey 2.5.0  OspreyGUI

I had no issues with importing my data. This isn’t an error I ran into before when I wasn’t including EtOH as a target and when I was using the default basis set. I saw in the file you sent that     = 0.55; 

whereas previously I used the default values of 0.4. Unsure if that would be related but figured I would mention it.

frontal.m (17.9 KB)

Hi @Claar727,

This is strange. From what I can see I’d say that your jobfile is correct, the Osprey version is correct (I assume that you have downloaded the develop branch?), and I have just tested again if it works for my GABA-GSH-EtOH data and it does. This means that there might be a problem during the data load. However, I am unable to debug this without a dataset.

Could you send me the MRS files of a single subject? You can use the deidentification tool in Osprey ( before sending.


Thank you for being so responsive! I have a conference coming up and want to use the data from this analysis so I really appreciate it.

I checked the in my Osprey directory and found these lines

[![Build Status](](
[![GitHub commit activity](](
[![GitHub last commit](](

so I would assume I am on the develop branch.

I tried to upload my dat files to the post but they are too large so I created a dropbox but I would prefer not to post the link here on a public form. Would you mind sharing an email address that I can grant access to the dropbox?

Also, thank you for letting me know you all already have a de-identify script. I was about to start writing my own. I’m not sure if it would be an overkill for de-identifying things but, if your software can detect if files are named according to BIDS, people might also want the subject ID removed from the file name itself. Something like if “sub-\d+” in file name replace the digits with “XXX”.

Hi @Claar727,

I analyzed the dataset you sent me and it works just fine. Now I can think of two possilbe reasons that it is not working for you:

  1. Is the dataset you sent me the first in your jobfile? It could be that this specific dataset has a problem. If the dataset is a different one could you try analyzing the same one on your machine?
  2. The file is your local version of what you can see on the GitHub page. The lines you are quoting are just the backend to create the badges and would look similar regardless of the version. Are you 100% sure that you have downloaded the most recent version? You can either redownload it or use a proper GitHub integration and merge the most recent online develop branch into your local branch.


Thanks for letting me know that about the github README. I will try a fresh download of the most recent version of Osprey and see if that works and let you know.

I did a fresh install and now it works! Thank you.

I can also confirm that I do now see an EtOH spectrum with the updated targets and basis set.