Chapter 4 The Osprey job file
Every Osprey analysis requires the user to provide a job file. The Osprey job file is the only direct point of contact between the user and the analysis. It contains paths to MRS data files and structural images, defines processing and modeling options, and determines whether (and where) output files are being saved.
The job file system ensures that all processing, modeling, and quantification steps are performed in an operator-independent, reproducible way.
4.1 Example job file
The following box contains the example job file jobSDAT.m, defining a batched analysis of the two Philips PRESS (TE = 30 ms) datasets that are included in the exampledata/sdat/ directory of the Osprey repository. You can click on the dropdown arrow on the right to take a look through the file, and then read on for a detailed description of each job file item.
Example job file jobSDAT.m:
%% 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.
%
% AUTHOR:
% Dr. Georg Oeltzschner (Johns Hopkins University, 2019-07-15)
% goeltzs1@jhmi.edu
%
% HISTORY:
% 2019-07-15: First version of the code.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% 1. SPECIFY SEQUENCE INFORMATION %%%
% Specify sequence type
seqType = 'unedited'; % OPTIONS: - 'unedited' (default)
% - 'MEGA'
% - 'HERMES'
% - 'HERCULES'
% Specify editing targets
editTarget = {'none'}; % 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'
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% 2. SPECIFY DATA HANDLING AND MODELING OPTIONS %%%
% 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];
% opts.ECC.mm = [0 1];
opts.ECC.raw = 1; % OPTIONS: - '1' (default)
opts.ECC.mm = 1; % - '0' (no)
% - [] array
% Save LCModel-exportable files for each spectrum?
opts.saveLCM = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save jMRUI-exportable files for each spectrum?
opts.savejMRUI = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save processed spectra in vendor-specific format (SDAT/SPAR, RDA, P)?
opts.saveVendor = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save processed spectra in NIfTI-MRS format?
opts.saveNII = 0; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save PDF output for all Osprey modules and subjects?
opts.savePDF = 0; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% 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.
opts.fit.includeMetabs = {'default'}; % OPTIONS: - {'default'}
% - {custom}
% Choose the fitting algorithm
opts.fit.method = 'Osprey'; % OPTIONS: - 'Osprey' (default)
% - 'LCModel'
% Choose the fitting style for difference-edited datasets (MEGA, HERMES, HERCULES)
% (only available for the Osprey fitting method)
opts.fit.style = '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
opts.fit.range = [0.5 4]; % [ppm] Default: [0.5 4]
opts.fit.rangeWater = [2.0 7.4]; % [ppm] Default: [2.0 7.4]
% Determine the baseline knot spacing (in ppm) for the metabolite spectra
opts.fit.bLineKnotSpace = 0.4; % [ppm] Default: 0.4.
% Add macromolecule and lipid basis functions to the fit?
opts.fit.fitMM = 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.:
% opts.fit.basisSetFile = 'osprey/fit/basis/3T/philips/mega/press/gaba68/basis_philips_megapress_gaba68.mat';
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% 3. SPECIFY MRS DATA AND STRUCTURAL IMAGING FILES %%
% 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 = fileparts(which(fullfile('exampledata','sdat','UnEdited','jobSDAT.m')));
% 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({subs.name},'sub'));
counter = 1;
for kk = 1:length(subs)
% Loop over sessions
sess = dir([subs(kk).folder filesep subs(kk).name]);
sess(1:2) = [];
sess = sess([sess.isdir]);
sess = sess(contains({sess.name},'ses'));
for ll = 1:length(sess)
% Specify metabolite data
% (MANDATORY)
dir_metabolite = dir([sess(ll).folder filesep sess(ll).name filesep 'mrs' filesep subs(kk).name '_' sess(ll).name '_press' filesep '*.SDAT']);
files(counter) = {[dir_metabolite(end).folder filesep dir_metabolite(end).name]};
% Specify water reference data for eddy-current correction (same sequence as metabolite data!)
% (OPTIONAL)
% Leave empty for GE P-files (.7) - these include water reference data by
% default.
dir_ref = dir([sess(ll).folder filesep sess(ll).name filesep 'mrs' filesep subs(kk).name '_' sess(ll).name '_press-ref' filesep '*.SDAT']);
files_ref(counter) = {[dir_ref(end).folder filesep dir_ref(end).name]};
% Specify water data for quantification (e.g. short-TE water scan)
% (OPTIONAL)
files_w = {};
% Specify metabolite-nulled data for quantification
% (OPTIONAL)
files_mm = {};
% Specify T1-weighted structural imaging data
% (OPTIONAL)
% Link to single NIfTI (*.nii) files for Siemens and Philips data
% Link to DICOM (*.dcm) folders for GE data
files_nii(counter) = {[sess(ll).folder filesep sess(ll).name filesep 'anat' filesep subs(kk).name filesep sess(ll).name '_T1w.nii.gz']};
% 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']}};
counter = counter + 1;
end
end
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Definitions without using BIDS
% You can always supply direct path to each of the files within
% the cell array. For example:
% Specify metabolite data
% (MANDATORY)
% 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!)
% (OPTIONAL)
% 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)
% (OPTIONAL)
% files_w = {};
% Specify metabolite-nulled data for quantification
% (OPTIONAL)
% files_mm = {};
% Specify T1-weighted structural imaging data
% (OPTIONAL)
% 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
% (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) = {{'/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'}};
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% 4. SPECIFY STAT FILE %%%
% 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)
% file_stat = fullfile(data_folder, 'stat.csv');
file_stat = '';
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% 5. SPECIFY OUTPUT FOLDER %%
% 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)
% (MANDATORY)
outputFolder = fullfile(data_folder, 'derivatives');
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%4.2 Specifying Sequence Information
In this section of the job file, some basic acquisition information is specified. These options inform data processing and modeling throughout the Osprey pipeline.
4.2.1 Sequence Type
The seqType variable describes the type of sequence used and is a required input in the form of a string.seqType determines whether the supplied datasets have been acquired with spectral editing experiments.
% Specify sequence type
seqType = 'unedited'; % OPTIONS: - 'unedited' (default)
% - 'MEGA'
% - 'HERMES'
% - 'HERCULES'4.2.2 Editing Targets
The editTarget variable describes the sequence type and is a required input in the form of a cell array. editTarget determines the target spin system(s) of spectral editing experiments. If no spectral editing has been performed, enter {'none'}.
% Specify editing targets
editTarget = {'none'}; % OPTIONS: - {'none'} (default if 'unedited')
% - {'GABA'}, {'GSH'}, {'Lac'}, {'PE322'}, {'PE398'} (for 'MEGA')
% - {'GABA', 'GSH'}, {'GABA', 'Lac'}, {'NAA', 'NAAG'} (for 'HERMES'and 'HERCULES')4.2.3 Data Scenario
The datascenario variable specifies the conditions in which the data were acquired.For in-vivo single-voxel MRS, select invivo. Further options are available for data acquired in a phantom, or multi-voxel data acquired with PRIAM or MRSI.
% Specify data scenario
dataScenario = 'invivo'; % OPTIONS: - 'invivo' (default)
% - 'phantom'
% - 'PRIAM'
% - 'MRSI'4.3 Data handling and modeling options
In this section of the job file, you provide information on whether you would like to save the processed data in externally usable file formats (for example, if you want to interface your analysis with LCModel), and specify options for the modeling.
4.3.1 Spectral registration options
The opts.SpecReg option allows the specification of the desired spectral registration method.
By setting opts.SpecReg to RobSpecReg, alignment is performed with lipid/water removal using simialrity meric, and weighted averaging.
By setting opts.SpecReg to ProbSpecReg, Probabilistic spectral alignment is performed, registering to a median target with weighted averaging.
By setting opts.SpecReg to RestrSpecReg, Spectral alignment using similarity metric and weighted average over a restricted 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'4.3.2 Sub-spectral alignment
opts.SubSpecAlignment allows specification of the metric used to optimize sub-spectral alignment. L2Norm is the default, with L1Norm as an alternative option. Choosing none will circumvent sub-spectral alignment altogether.
opts.SubSpecAlignment.mets = 'L2Norm'; % OPTIONS: - 'L2Norm' (default)
% - 'L1Norm'
% - 'none'4.3.3 Eddy-current correction
opts.ECC specifies the data to be eddy-current corrected using a corresponding water-unsuppressed reference scan (Klose, Magn Reson Med 14:26-30 (1990)). The sub-structures opts.ECC.raw and opts.ECC.mm correspond to the raw metabolite and macromolecule spectra, respectively. opts.ECC.raw and opts.ECC.mm may be specified as 1 to apply ECC to all data, 0 to not apply ECC at all, or as a vector to apply ECC to a sub-set of the data.
%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];
% opts.ECC.mm = [0 1];
opts.ECC.raw = 1; % OPTIONS: - '1' (default)
opts.ECC.mm = 1; % - '0' (no)
% - [] array4.3.4 Saving data to external formats
The opts.save variable set determines whether Osprey saves the processed data in formats that can be interfaced with external analysis software.
By setting opts.saveLCM to 1, LCModel-readable .RAW files are produced.
By setting opts.saveJMRUI to 1, jMRUI/Tarquin-readable .TXT files are produced.
By setting opts.saveVendor to 1, single vendor-specific files are created, i.e. .SDAT/.SPAR files for Philips data, and .RDA files for Siemens data, regardless of the raw data format.
By setting opts.saveNII to 1, processed spectra are produced in the NIfTI-MRS format.
By setting opts.savePDF to 1, PDF summaries are produced for all subjects after running each module.
% Save LCModel-exportable files for each spectrum?
opts.saveLCM = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save jMRUI-exportable files for each spectrum?
opts.savejMRUI = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save processed spectra in vendor-specific format (SDAT/SPAR, RDA, P)?
opts.saveVendor = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save processed spectra in NIfTI-MRS format?
opts.saveNII = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)
% Save PDF output for all Osprey modules and subjects?
opts.savePDF = 1; % OPTIONS: - 0 (no, default)
% - 1 (yes)LCModel .RAW files can be loaded via the Other option in the LCModel file type selection menu.
Please be aware that LCModel may prompt you to enter the number of FID data points (a positive integer number, e.g. 2048), dwell time (in seconds, e.g. 0.0005), and the static magnetic field strength in MHz (e.g. 123.26 for a Siemens 2.89 T magnet).
In addition to the .RAW files, Osprey also creates the corresponding .CONTROL files. These files can be used for LCModel batch processing.
for file in /storage/LCModelControlFiles/*;
do /usr/local/.lcmodel/bin/lcmodel < $file;
done .CONTROL files you have to specify the following mandatory variables in the osp_lcmcontrol_params() function located in the process folder: key, FILBAS, FOLDER, and DOECC.
key = 0; %Your LCM key goes here
FILBAS = '/storage/myBasisSet_30ms_PRESS.BASIS'; % Location of .BASIS file used in LCModel
FOLDER = '/storage/LCMoutput'; %Output folder (Create this on your linux machine first)
DOECC= 'F'; % No eddy current correction in LCModel as this is already performed in Osprey.osp_lcmcontrol_params() function.
When loading .TXT files with Tarquin, you will probably need to enter the echo time in seconds (e.g. 0.03 for a TE = 30 ms acquisition).
The opts.saveVendor switch has been introduced to sidestep these problems with .RAW and .TXT files. LCModel, TARQUIN and jMRUI accept the .SDAT/.SPAR and .RDA file formats, and should be able to read the header information correctly.
All exported third-party format files are stored in sub-directories of the output folder specified further down in the job file.
4.3.5 Matbolites included in the basis-set
opts.fit.includeMetabs can be used to specify a custom set of metabolites to be included in the fitting. By default, all of the metabolites listed below are included, but a subset may be specified as a cell array of strings:
opts.fit.includeMetabs = {Cr, CrCH2, GABA, PCr,...}
% 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.
opts.fit.includeMetabs = {'default'}; % OPTIONS: - {'default'}
% - {custom}opts.fit.basisSetFile may be manually specified to bypass the Osprey automatic selction, or to specify an alternative. opts.fit.basisSetFile is a string specifying the path to the basis set stored in FID-A format.
% 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.:
% opts.fit.basisSetFile = 'osprey/fit/basis/3T/philips/mega/press/gaba68/basis_philips_megapress_gaba68.mat';
### Specifying modelling algorithmThe opts.fit.method variable set determines the modeling algorithm used to fit the processed spectra. The default is to use the Osprey method, as described in the publication, but Osprey can also utilize LCModel for fitting. If LCModel is specified, Osprey will generate .RAW files of the processed spectra, populate minimal control files, and read the outputs back into the Matlab container.
% Choose the fitting algorithm
opts.fit.method = 'Osprey'; % OPTIONS: - 'Osprey' (default)
% - 'LCModel'4.3.6 LCModel-specific options
If LCModel is used as a method, further options may be specified. opts.fit.basisSetFileis a string specifying the path to a basis file. opts.fit.controlFile is a string specifying the path to a control file. File-specific entries of the control file will be populated by Osprey, allowing you to simply specify a generic control file template.
opts.fit.basisSetFile = '/storage/LCModelBasisFiles/MyBasis.basis';
% Specify LCModel-type control file (.CONTROL)
% This is optional: If you leave this field blank, Osprey will create a
% minimum control file for you.
opts.fit.controlFile = '/storage/LCModelControlFiles/MyControl.control');4.3.7 Fit style
The opts.fit.style variable set determines how difference-edited data are modeled.
By setting opts.fit.style to Concatenated, the difference and sum spectra in MEGA, HERMES and HERCULES datasets will be modeled simultaneously, i.e. with common metabolite amplitude parameters across these spectra.
By setting opts.fit.style to Separate, the difference and edit-OFF spectra in MEGA, HERMES and HERCULES datasets will be modeled independently. In this case, the creatine reference signal will be determined from the edit-OFF spectrum.
% Choose the fitting style for difference-edited datasets (MEGA, HERMES, HERCULES)
% (only available for the Osprey fitting method)
opts.fit.style = 'Concatenated'; % OPTIONS: - 'Concatenated' (default) - will fit DIFF and SUM simultaneously)
% - 'Separate' - will fit DIFF and OFF separately4.3.8 Fitting range
The opts.fit.range and opts.fit.rangeWater variables determine the fitting range (in ppm) of the metabolite and water spectra, respectively.
% Determine fitting range (in ppm) for the metabolite and water spectra
opts.fit.range = [0.5 4]; % [ppm] Default: [0.5 4]
opts.fit.rangeWater = [2.0 7.4]; % [ppm] Default: [2.0 7.4]The opts.fit.GAP option specifies a range (in ppm) to be excluded from the fitting of specified sub-spectra. The input is a vector specifying the upper and lower bounds of the range.
opts.fit.GAP.A = [];
opts.fit.GAP.diff1 = [];4.3.9 Baseline knot spacing
The opts.fit.bLineKnotSpace variable determines the spacing (in ppm) between two adjacent knots of the cubic B-spline baseline. This parameter is equivalent to the DKNTMN parameter in LCModel.
Higher values correspond to a stiffer baseline, while lower values will produce a larger number of spline knots, allowing for greater flexibility of the baseline.
% Determine the baseline knot spacing (in ppm) for the metabolite spectra
opts.fit.bLineKnotSpace = 0.4; % [ppm] Default: 0.4.Choosing lower values for the bLineKnotSpace variable will improve the fit quality at the expense of overparametrization of the model. LCModel uses a default knot spacing of DKNTMN = 0.15, i.e. 0.15 ppm, which likely allows too much flexibility. In the absence of baseline regularization in the current stage of the Osprey model development, we chose to restrict baseline flexibility by opting for a default value of 0.4 ppm.
4.3.10 Macromolecule and lipid signals
The opts.fit.fitMM variable determines whether simulated Gaussian signals representing broad macromolecular and lipid signals are included in the basis set.
By default, Osprey includes these basis functions. If you want to use an experimentally measured MM/lipid basis function, or operate at long echo times where the MM and lipid resonances have decayed, you can set opts.fit.fitMM = 0 to exclude them.
% Add macromolecule and lipid basis functions to the fit?
opts.fit.fitMM = 1; % OPTIONS: - 0 (no)
% - 1 (yes, default)4.3.11 Co-edited macrommolecules
opts.fit.coMM3 specifies the approach to modeling the co-edited macromolecule resonance at 3ppm for GABA-edited MRS experiments. By default a 14 Hz Gaussian peak is used as basis function. the options are as follows:
1. 3to2MM - uses a fixed 3 to 2 amplitude ratio between the 0.93-ppm-MM peak and the co-edited 3.0-ppm-MM peak by generating a single composite basis function
2. 3to2MMsoft - uses a soft constraints during the modeling to enforce 3 to 2 amplitude ratio between the 0.93-ppm-MM peak and the co-edited 3.0-ppm-MM peak
3. 1to1GABA. - uses a fixed 1 to 1 amplitude ratio between the GABA and the co-edited 3.0-ppm-MM peak by generating a single composite basis function
4. 1to1GABAsoft - uses a soft constraints during the modeling to enforce 1 to 1 amplitude ratio between the GABA and the co-edited 3.0-ppm-MM peak
5. freeGauss - uses a separate basis function for the co-edited 3.0-ppm-MM peak with an initial 14 Hz FWHM of the Gaussian basis function
6. fixedGauss - uses a separate basis function for the co-edited 3.0-ppm-MM peak, however, the FWHM of the Gaussian basis function is optimized during the modeling process
7. none - uses no MM basis function for the co-edited 3.0-ppm MM in the difference spectrum.
% How do you want to model the co-edited macromolecules at 3 ppm for GABA-edited MRS?
opts.fit.coMM3 = 'freeGauss'; % OPTIONS: - {'3to2MM'} (default)
% - {'3to2MMsoft'}
% - {'1to1GABA'}
% - {'1to1GABAsoft'}
% - {'freeGauss'}
% - {'fixedGauss'}
% - {'none'}4.4 Specifying MRS data and structural imaging files
In this section of the job file, you specify the full paths to your MRS data and structural imaging files.
Osprey is designed for the batch analysis of multiple datasets in one session. Each dataset corresponds to an element of a cell array. The cell arrays for metabolite data, water reference data, short-TE water data, and structural imaging files need to have the same number of elements. For example, if you have MRS data from two voxels in the same subject, you need to enter the path to the .NII structural twice into the files_nii cell array.
At the current stage of implementation, you can only analyze one type of sequence per job file, i.e. if you have MEGA-PRESS and PRESS data for each subject, you will have to design two separate job files for MEGA-PRESS and PRESS data.
4.4.1 Metabolite data
The files variable is defined as a cell array of full paths to the raw MRS data files containing your metabolite (water-suppressed) data.
% Specify metabolite data
% (MANDATORY)
files = {which('exampledata/sdat/sub-01/mrs/sub-01_press/sub-01_PRESS_35_act.sdat'),...
which('exampledata/sdat/sub-02/mrs/sub-02_press/sub-02_PRESS_35_act.sdat')};In the job files in the exampledata folder of the Osprey repository, the which function ensures that the paths are correctly defined regardless of where you put your Osprey folder. When designing your own job file, you will have to provide the full paths to your raw data, e.g.:
% Specify metabolite data
% (MANDATORY)
files = {'/Users/Georg/Documents/MRSData/study-01/sub-01/mrs/sub-01_press/sub-01_PRESS_35_act.sdat',...
'/Users/Georg/Documents/MRSData/study-01/sub-02/mrs/sub-02_press/sub-02_PRESS_35_act.sdat',};Instead of writing out the full paths explicitly, you can also create a procedure that is tailored to your local file organization, as long as you end up with a files cell array containing an element for each file you want to analyze.
MRS raw data can be exported in DICOM and Siemens RDA format, where each average is saved as a separate .DCM or .RDA file. In this case, you have to enter the full path to the folder containing all single-average files belong to one acquisition.
4.4.2 Lineshape reference data
The files_ref variable is defined as a cell array of full paths to the raw MRS data files to your lineshape (water-unsuppressed) reference data.
These are an optional input, acquired with the same sequence as the metabolite data, but without water suppression, and used to perform eddy-current correction of the metabolite data.
% Specify water reference data for eddy-current correction (same sequence as metabolite data!)
% (OPTIONAL)
% Leave empty for GE P-files (.7) - these include water reference data by
% default.
files_ref = {which('exampledata/sdat/sub-01/mrs/sub-01_press-ref/sub-01_PRESS_35_ref.sdat'),...
which('exampledata/sdat/sub-02/mrs/sub-02_press-ref/sub-02_PRESS_35_ref.sdat')};If only lineshape reference data are provided, this signal is also used to calculate water-scaled concentration estimates.
4.4.3 Short-TE water data
The files_w variable is defined as a cell array of full paths to the raw MRS data files to short-TE water data.
These are another optional input, and can be used to derive water-scaled concentration estimates (while lineshape reference data are only used for eddy-current correction). Using short-TE water as the concentration reference standard reduces T2-weighting of the water reference signal (and associated correction errors) compared to long-TE water data.
% Specify water data for quantification (e.g. short-TE water scan)
% (OPTIONAL)
files_w = {which('exampledata/sdat/sub-01/mrs/sub-01_press-ref/sub-01_PRESS_35_ref.sdat'),...
which('exampledata/sdat/sub-02/mrs/sub-02_press-ref/sub-02_PRESS_35_ref.sdat')};4.4.4 Structural images
The files_nii variable is defined as a cell array of full paths to T1-weighted structural images used for co-registration and segmentation purposes.
Osprey requires NIfTI (.nii) files to be supplied. For GE files, you may also provide the full path to a directory containing the DICOM folders corresponding to the T1 acquisition.
% Specify T1-weighted structural imaging data
% (OPTIONAL)
% Link to single NIfTI (.nii) files for Siemens and Philips data
% Link to DICOM (.dcm) folders for GE data
files_nii = {which('exampledata/sdat/sub-01/anat/sub-01_T1w.nii'),...
which('exampledata/sdat/sub-02/anat/sub-02_T1w.nii')};Osprey uses SPM12 functions to load and process structural images. Please refer to the installation instructions for information on how to set up SPM12.
% 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']}};4.4.5 Specifying stat file
In this section of the job it is possible to specify the location of a csv file containing group variables, and possible correlation measures.
% 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)
% file_stat = fullfile(data_folder, 'stat.csv');
file_stat = '';4.4.6 Specifying the output folder
In this section of the job file, you specify the full paths to an output folder where the Osprey data container is saved in .mat format. In addition, any exported files (for use with jMRUI, TARQUIN, or LCModel) will be saved in separate sub-folders of the output folder.
The outputFolder variable specifies a full path to the output folder.
% Specify output folder
% (MANDATORY)
outputFolder = strrep(which('exampledata/sdat/jobSDAT.m'),'jobSDAT.m','derivatives');In the job files in the example folder of the Osprey repository, the which and strrep functions ensures that an output folder derivatives in the folder where the job file jobSDAT resides. When designing your own job file, you will have to provide the full path to your desired output folder.
Note that Osprey detects if the output folder already exists and contains data from a previous analysis. In this case, you will be prompted whether you would like to overwrite the existing output.