Options#

Turbo has a large amount of parameters that each can be set individually. These are split to 3 separate categories:

  1. Turbo specific parameters: Used to control behavior of the program.

  2. Modelling parameters: Used to control what model is used and with what parameters.

  3. Magia options: Used to control Magia.

These parameter options can be fetched from the dicom data or set to some default value. User can however change these as they see fit.

Using non-default options#

To change default options see Example 3: Use non-default options.

Controlling the flow of program#

These options are Turbo specific. The full list of possible options are below. All of these options are given in a struct named turbo_options. Here they are sectioned for easier reading.

Warning

Complete this list later.

Note

If function parameter says ‘options’, this means Matlab name-value argument, see more at https://se.mathworks.com/help/matlab/matlab_prog/validate-name-value-arguments.html.

set_turbo_options(options)#

Creates a struct containing settings for TURBO with default values.

Parameters:

  • frametimes (Nx2 array, default : []) – Frametimes of the scan.

  • tracer (char array, default : '') – Used tracer

Returns:

turbo_options – Struct containing all parameters controlling turbo. These values are set to default. You can modify these by altering the field values.

Return type:

struct

Notes

There are also separate parameter structs study_info, modelling_options and magia_options that need to be initialized separately.

Below are the comprehensive list of all generic options for turbo controls and explanations how to use them.

Turbo options#

Option parameter

Explanation

use_parfor

int, default : 0

Controls whether certain functions in Turbo are run in parallel. These are ROI extraction and ROI modelling.

  • 0 no parallelisation.

  • 1 use parallelisation (parpool size set by user before execution).

greedy_threads

int, default : 5

Controls the number of threads are used for greedy-coregistration. If use_parfor = 1, the thread number should be kept low.

run_preprocessing

int, default : 1

Skipping this step saves time and computation if it is already done.

  • 0 to skip preprocessing.

  • 1 to run preprocessing.

use_highres_segmentation

int, default : 0

If you don’t have a GPU, best quality segmentation can take several hours.

  • 0 to run faster but poorer quality segmentation (good if you don’t have a GPU).

  • 1 to use the best quality (use this if you have GPU).

roinames

(N,1) string array, default : read from labels.txt

List of roinames. By default taken from label .txt file supplied.

use_elastic_mc

int, default : 1

Motion correction is done using greedy coregistration. This step may take some time. This value also defines if the motion corrected version of the image is used later in the modelling.

  • 0 to skip motion correction.

  • 1 to use motion correction.

use_ct_coreg

int, default : 1

CT is coregistered to PET image using greedy coregisration.

elastic_mc_start_frame

int, default : 0

Frames from elastic_mc_start_frame to end are elastically motion corrected. This is done to the whole PET image.

  • 0, automatically selects the starting frame. The starting frame is selected for FDG using NCC and for H2O the frame after tracer peak.

  • Any integer > 0, use this as the starting frame.

rigid_mc_start_frame

int, default : 0

Frames from rigid_mc_start_frame to end are rigidly motion corrected. This is done to heart image only.

  • 0, start frame is determined from non-corrected input. Start frame is the first frame after the input exceeds 1% of the total input integral.

  • Any integer > 0, this is used as the starting frame.

run_qc

int, default : 1

Creates images and graphs to quickly glance over if motion correction was successful.

  • 0, skip quality control for motion correction.

  • 1, do quality control for motion correction.

extract_TACs

int, default : 1

This has to be done before running modelling.

  • 0, skip extracting all average ROI TACs.

  • 1, extract all ROI TACs.

extract_IDIFaorta_input

int, default : 1

This has to be done before running modelling. Used PET file depends on modelling_options.input_type.

  • 0, skip extracting automatic input function.

  • 1, extract automatic input function.

run_heart_mc

int, default : 1

Run rigid motion correction for heart and get automatic input from this motion corrected heart.

  • 0, to skip heart rigid motion correction. If this step has been done previously, the motion corrected input can still be used.

  • 1, to do motion correction for heart and using

run_modelling

int, default : 1

Runs modelling for all selected ROIs. Also runs voxel level modelling, if modelling_options.run_vox_modelling = 1.

  • 0, skip modelling.

  • 1, run modelling.

crop_brains

int, default : 1

This has to be done before running Magia.

  • 0 to skip brain crop and align.

  • 1 to do brain crop and align.

run_magia

int, default : 1

  • 0, skip Magia brain modelling.

  • 1, run Magia brain modelling.

compress_niftis

int, default : 1

  • 0 output images are .nii files.

  • 1 output images are .nii.gz files.

ref_frame

int

Determines the frame used for motion correction. Other frames are aligned to match this frame. Different defaults are used for different tracers:

  • H2O default: middle frame.

  • FDG default: last frame.

verbose

int, default : 0

Level of printing info to console.

  • 0, no printing.

  • 1, some general information.

  • 2, print also information about modelling process.

  • 5, also save intermediate images during the automatic input derivation.

rethrow_error

int, default : 0

  • 0, program runs normally

  • 1, rethrows errors during modelling that are skipped during normal execution.

run_dicom_conversion_only

int, default : 0

  • 0, program runs normally.

  • 1, program stops execution after dicom conversion.

run_segmentation only

int, default : 0

  • 0, program runs normally.

  • 1, program stops execution after segmentation is done.

Modelling options#

Modelling options are similar to turbo_options, but control only things related to modelling. Modelling is only run if turbo_options.run_modelling = 1.

set_modelling_options()#

Creates a default modelling options struct for run_totalbody_turbo. TODO add comments for each parameter.

Parameters:

  • tracer (char array) – Tracer determines used model (to some extent).

  • frametimes (Nx2 double array) – Frametimes used in the study.

Returns:

modelling_options – Modelling options struct for run_totalbody_turbo that contains default options.

Return type:

struct

Option parameter

Explanation

ROImodel

char array

Model used for modelling. Possible values are:

  • fit_h2o (H2O)

  • patlak (FDG)

  • fur (FDG)

  • logan (FDG) (not yet implmented)

  • suv (all tracers)

n_iter

int, default : 100

Iteration count for nonlinear fitting done for fit_h2o. Used only for H2O studies.

VOXmodel

char array

Model used for voxel level modelling. Models are:

  • imgflowm (H2O)

  • imgpatlak (FDG)

  • imgfur (FDG)

  • imglogan (FDG) (not implemented yet)

  • imgsuv (any tracer)

lb

(1,4) or (1,6) double array, default : [0, 0.001, 0, -60]

Used only for H2O studies. Lower bounds for fitting. From left to right, these values correspond to K1, k1/k2, Va. The units of the bounds are:

  • K1: ml/(sec*ml)

  • k2: 1/sec (when solved from K1/k2 which is unitless)

  • Va: vascular fraction

  • Delay: sec

ub

(1,4) or (1,6) double array, default : [0.1, 1, 0.25, 60]

Used only for H2O studies. Upper bounds for fitting. From left to right, these values correspond to K1, k1/k2, Va. The units of the bounds are:

  • K1: ml/(sec*ml)

  • k2: 1/sec (when solved from K1/k2 which is unitless)

  • Va: vascular fraction

  • Delay: sec

roi_fit_lengths

(n_rois, 1) double array

Drop data after this timepoint, separate values for each ROI. Value at roi_fit_lengths(i) corresponds to ROI at roinames(i). Units are in seconds. This is only for H2O!. Defaults are:

  • fit_h2o: Ending of the last frame.

roi_start_times

(n_rois, 1) double array

Drop data before this timepoint. Separate start time for each ROI. This is only for FDG!. Value at roi_start_times(i) corresponds to ROI at roinames(i). Units are in minutes. Defaults are:

  • Patlak, FUR, Logan: 15 minutes for all ROIs.

  • SUV: Starting time of the first frame.

roi_end_times

(n_rois, 1) double array

Drop data after this timepoint. Separate end time for each ROI. This is only for FDG!. Value at roi_end_times(i) corresponds to ROI at roinames(i). Units are in minutes. Defaults are:

  • Patlak, FUR, Logan, SUV: Ending time of the last frame.

run_vox_modelling

int, default : 1

Controls whether the voxel level modelling is run or not.

  • 0, do not run voxel level modelling.

  • 1, run voxel level modelling.

use_tpclib

int, default : 0

Determines if the used modelling library is tpcclib instead of Matlab library.

  • 0, Matlab library is used (recommended).

  • 1, tpcclib is used.

input_type

char array, default : ‘IDIFaorta_mc_rigid’

Determines what input function is used when doing modelling. Possible values are:

  • IDIFaorta_no_mc, there is no correction applied to the PET image before extracting input function.

  • IDIFaorta_mc_rigid, heart region is rigidly corrected for motion before extracting input function.

  • IDIFaorta_mc_elastic, whole PET image is corrected elastically before extracting input function (not implemented at the moment).

processed_roi_idx

(n_rois, 1) int array, default : [1:123]

Array of the ROI indices that will be processed. For example processed_roi_idx = [1, 2, 90, 5] runs the modelling for spleen, right kidney, brain and liver (from the roinames.txt list). To run all ROIs this value can be set to [1:123] or ‘all’.

filter_size

int, default : NaN

Filter size in millimetres. The smooth is applied to the dynamic image before calculating parametric images. If this value is set to NaN no smoothing is done.

vox_start_time

double, default : 15 (minutes)

Drop data before this timepoint. Works the same way as roi_start_times, but this is specific to voxel modeling only. This is only for FDG!

vox_end_time

double, default : 50 (minutes)

Drop data after this timepoint. Works the same way as roi_end_times, but this is specific to voxel modeling only. This is only for FDG!

vox_fit_length

double, default : frametimes(2,end) (seconds)

Drop data after this timepoint. Works the same way as roi_fit_lengths option, but this is specific to voxel modeling only. This is only for H2O!

fit_va

int, default : 0

Affects only when modelling_options.VOXmodel = 'imgh2o'.

  • 0, Va is set to 0 in voxel level modelling.

  • 1, Va is fitted normally during voxel level modelling.

calculate_R2_img

int, default : 1

Also saves R^2 parametric image to see which areas are well fitted. This is only for H2O!

magia_cut_time

int, default : frametimes(end, 2)

Data is used up to this timepoint, by default all data is used.

fit_length_timeunit

char array, default : ‘sec’

Sets the units of roi_fit_lengths and vox_fit_length. This option is to make the unit unambiguous, as H2O modelling uses seconds and FDG minutes. It is recommended to not change this.

  • sec, roi_fit_lengths and vox_fit_length values are interpreted as seconds.

  • min, roi_fit_lengths and vox_fit_length values are interpreted as minutes.

start_end_timeunit

char array, default : ‘min’

Sets the units of roi_start_times, roi_end_times, vox_start_times and vox_end_times. This option is to make the unit unambiguous, as H2O modelling uses seconds and FDG minutes. It is recommended to not change this.

  • sec, roi_start_times, roi_end_times, vox_start_times and vox_end_times values are interpreted as seconds.

  • min, roi_start_times, roi_end_times, vox_start_times and vox_end_times values are interpreted as minutes.

clustered_rois

(clustered_rois_nr, 1) string array, default [“kidney_right”; “kidney_left”]

A list of ROIs that will be clustered from parametric image. Results are gathered separately from these clustered ROIs.

Magia options#

Option parameter

Explanation

model

char array , default : modelling_options.ROImodel

By default, uses the same model as ROI model for the totalbody modelling. Possible values are:

  • suv

  • suvr

  • srtm

  • two_tcm

  • logan

  • logan_ref

  • patlak

  • patlak_ref

  • ma1

  • fur

  • one_tcm

  • fit_h2o

cpi

int, default : 1

  • 0, parametric images are not calculated.

  • 1, parametric images are calculated.

rc

int, default : 1

Determines if data based ROI-correction if used.

  • 0, no ROI correction.

  • 1, ROI correction is used.

cut_time

double, default : frametimes(2, end)

  • 0, use all data.

  • Any other double, data is cut after this timepoint.

roi_type

char array, default : ‘atlas_native’

Determines what ROIs are used. Possible values are:

  • atlas

  • atlas_native

  • freesurfer

norm_method

char array, default : ‘pet’

Determines what spatial normalisation is used. Possible values are:

  • pet

  • mri

mni_roi_mask_dir

char array, default : [TURBO_dir filesep ‘AAL_rois’]

Path where the MNI ROI masks are. These are supplied with Turbo and this value should not be changed unless you know what you are doing.

template

char array, default : [TURBO_dir filesep ‘template’ filesep tracer_template.nii]

Template brain nifti file used for coregistration. These are supplied with Turbo and this value should not be changed unless you know what you are doing.

input_type

char array, default : depends on tracer

Input function type. Possible values are:

  • IDIFaorta_no_mc, there is no correction applied to the PET image before extracting input function.

  • IDIFaorta_mc_rigid, heart region is rigidly corrected for motion before extracting input function.

  • IDIFaorta_mc_elastic, whole PET image is corrected elastically before extracting input function (not implemented at the moment).

fwhm_roi

int, default : 0

Kernel size for enlargening ROIs.

fwhm_pre

int, default : 2

Smooth kernel size before voxel-level modelling. Units are millimetres.

fwhm_post

int, default : 8

Smooth kernel size before spm analysis. Units are millimetres.

mc_ref_frame

int, default : turbo_options.ref_frame

Reference frame for motion correction.

mc_fwhm

int, default : 7

SPM motion correction smooth parameter. Units are millimetres.

mc_rtm

int, default : 1

Defines whether the motion-correction should be done in two steps.

dc

int, default : study_specs.dc

  • 0, data is not decay corrected.

  • 1, data is decay corrected.

mc_excluded_frames

char array, default : frames before 20s

These frames are excluded from the motion correction because early frames might have low signal in brain due to lack of tracer. Format is '1,2,3,4'.

gu

int, default : study_specs.gu

Defines whether Magia should automatically convert the Ki values (from Patlak) or FUR-values into glucose uptake -estimates.

  • 0, Magia doesn’t convert Ki or FUR to glucose uptake.

  • 1, Magia converts Ki or FUR to glucose uptake.