Modelling wrappers#

modelling_wrapper_matlab(subject, study_specs, turbo_specs, modelling_options, petfile, frametimes, tac, inputdata, mask_idx, roiname, results_dir, options)#

Wrapper function that performs ROI-level parameter estimation and parametric images

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • study_specs (struct) – Study specific information.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • petfile (char array) – Full path to the PET file, e.g. /my/nifti/file.nii.

  • frametimes (2xN array) – Frame start and end times in an array.

  • tac (Nx1 double array) – Average TAC of the ROi.

  • inputdata (2xM array) – Input measure times and time activity curve.

  • mask_idx (Vx1 array) – ROI mask in linear index format.

  • roiname (char array) – Name of the processed ROI.

  • results_dir (char array) – Parent directory where the results are saved under separate folders.

  • fit_length (double, default : frametimes(end, 2)) – Include only TAC from 0 to fit_length.

Returns:

  • roi_warning (char array) – Gives information about warnings during modelling.

  • varargout{1} (double) – Fitdelay result, NaN if skipped.

  • varargout{2} (1xP double array) – List of estimated parameters.

  • varargout{3} (1xP string array) – List of names for estimated parameters, indices corresponding each other.

  • varargout{4} (1xP string array) – List of units for estimated parameters, indices corresponding each other.

  • varargout{5} (VxP double array) – This is a list of parameter estimates for the ROI. Let varargout{5} = vox_par_est and v be some row of vox_par_est. Then vox_par_est(v) corresponds to parameter estimates for voxel at pet_img_3d(mask_idx(v)). Keep in mind that mask_idx is in linear form (1D list).

  • varargout{6} (1xP string array) – List of names for estimated voxel parameters, indices corresponding each other.

modelling_wrapper_tpc(subject, study_specs, turbo_specs, modelling_options, petfile, tac, inputfile, mask_idx, roiname, results_dir, options)#

Wrapper function that performs ROI-level parameter estimation and parametric images

Uses TPCCLIB for modelling function implementations. See more at: https://gitlab.utu.fi/vesoik/tpcclib.

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • study_specs (struct) – Study specific information.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • petfile (char array) – Full path to the PET file, e.g. /my/nifti/file.nii.

  • tac (Nx1 double array) – Average TAC of the ROi.

  • inputfile (char array) – Full path to the inputfile, e.g. /my/input/file.txt.

  • mask_idx (Vx1 array) – ROI mask in linear index format.

  • roiname (char array) – Name of the processed ROI.

  • results_dir (char array) – Parent directory where the results are saved under separate folders.

  • fit_length (double, default: study_specs.frames(end, 2)) – Include only TAC from 0 to fit_length.

Returns:

  • roi_warning (char array) – Gives information about warnings during modelling.

  • varargout{1} (double) – Fitdelay result, NaN if skipped.

  • varargout{2} (1xP double array) – List of estimated parameters.

  • varargout{3} (1xP string array) – List of names for estimated parameters, indices corresponding each other.

  • varargout{4} (1xP string array) – List of units for estimated parameters, indices corresponding each other.

  • varargout{5} (VxP double array) – This is a list of parameter estimates for the ROI. Let varargout{5} = vox_par_est and v be some row of vox_par_est. Then vox_par_est(v) corresponds to parameter estimates for voxel at pet_img_3d(mask_idx(v)). Keep in mind that mask_idx is in linear form (1D list).

  • varargout{6} (1xP string array) – List of names for estimated voxel parameters, indices corresponding each other.

run_input_delay_correction_tpc(subject, turbo_specs, modelling_options, dftfilename_tac, inputfile, roiname, fit_length)#

Estimates H2O delay with NNLS.

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • study_specs (struct) – Study specific information.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • dftfilename_tac (char array) – Full file path to the dftfile, .e.g /my_dft/file.dft. See http://www.turkupetcentre.net/petanalysis/format_tpc_dft.html for more info about dft-files.

  • inputfile (char array) – Full path to the inputfile, e.g. /my/input/file.txt.

  • roiname (char array) – Name of the processed ROI.

  • fit_length (double) – Include only TAC from 0 to fit_length.

Returns:

input_dly – Estimated input curve delay.

Return type:

double

run_TBPET_ROI_modelling(subject, study_specs, turbo_specs, modelling_options, frametimes, tac, inputdata, roiname, results_dir, options)#

Does ROI-level modelling.

Currently supported models are:

  • H2O (non-linear fit)

  • FDG (Patlak fit)

  • FDG (FUR)

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • study_specs (struct) – Study specific information.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • frametimes (2xN array) – Frame start and end times in an array.

  • tac (Nx1 double array) – Average TAC of the ROi.

  • inputdata (2xM array) – Input measure times and time activity curve.

  • roiname (char array) – Name of the processed ROI.

  • results_dir (char array) – Parent directory where the results are saved under separate folders.

  • fit_length (double, default: frametimes(end, 2)) – Include only TAC from 0 to fit_length.

  • fitdelay_dly (double, default: 0) – For H2O. This is the previous delay estimated with fitdelay. The input curve is first shifted with this value and

Returns:

  • roi_warning (char array) – Gives information about warnings during modelling.

  • varargout{1} (1xP double array) – List of estimated parameters.

  • varargout{2} (1xP string array) – List of names for estimated parameters, indices corresponding each other.

  • varargout{3} (1xP string array) – List of units for estimated parameters, indices corresponding each other.

  • varargout{4} (double array) – Fitted curve.

run_TBPET_ROI_modelling_tpclib(subject, study_specs, turbo_specs, modelling_options, dftfilename_tac, inputfile, roiname, results_dir, options)#

Does ROI-level modelling using TPCCLIB.

Currently supported models are:

  • H2O (non-linear fit)

  • FDG (Patlak fit)

  • FDG (FUR)

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • study_specs (struct) – Study specific information.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • dftfilename_tac (char array) – Full file path to the dftfile, .e.g /my_dft/file.dft. See http://www.turkupetcentre.net/petanalysis/format_tpc_dft.html for more info about dft-files.

  • inputfile (char array) – Full path to the inputfile, e.g. /my/input/file.txt.

  • roiname (char array) – Name of the processed ROI.

  • results_dir (char array) – Parent directory where the results are saved under separate folders.

  • fit_length (double, default: frametimes(end, 2)) – Include only TAC from 0 to fit_length.

Returns:

  • roi_warning (char array) – Gives information about warnings during modelling.

  • varargout{1} (1xP double array) – List of estimated parameters.

  • varargout{2} (1xP string array) – List of names for estimated parameters, indices corresponding each other.

  • varargout{3} (1xP string array) – List of units for estimated parameters, indices corresponding each other.

  • varargout{4} (double array) – Fitted curve.

run_TBPET_VOX_modelling()#
run_TBPET_VOX_modelling_tpclib(subject, turbo_specs, modelling_options, petfile, inputfile, roiname, results_dir, options)#

Run voxel level-modelling using TPCCLIB.

Currently supported models are:

  • H2O (non-linear fit)

  • FDG (Patlak fit)

  • FDG (FUR)

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • petfile (char array) – Full path to the PET file, e.g. /my/nifti/file.nii.

  • frametimes (2xN array) – Frame start and end times in an array.

  • inputdata (2xM array) – Input measure times and time activity curve.

  • roiname (char array) – Name of the current ROI.

  • results_dir (char array) – Parent directory where the results are saved under separate folders.

  • mask_idx (double, default: []) – Logical array or linear index list corresponding to the modelled mask.

  • fit_length (double, default: frametimes(end, 2)) – Include only TAC from 0 to fit_length (H2O only).

  • save_rois (logical, default: 0) –

    H2O only.

    0, does not save individual ROI images. 1, saves individual ROI images. This may take a significant amount of space (~90GB space).

Returns:

  • varargout{1} (VxP double array) – This is a list of parameter estimates for the ROI. Let varargout{5} = vox_par_est and v be some row of vox_par_est. Then vox_par_est(v) corresponds to parameter estimates for voxel at pet_img_3d(mask_idx(v)). Keep in mind that mask_idx is in linear form (1D list).

  • varargout{2} (1xP string array) – List of names for estimated voxel parameters, indices corresponding each other.

totalbody_turbo_modelling(subject, study_specs, turbo_specs, modelling_options, petfile, frametimes, inputdata, tacdata, resliced_ct_seg_file, results_dir, options)#

Mathematical modelling for a PET image.

Mathematical modelling for all ROI’s in a PET image. Supports h2o, Patlak and FUR modelling (more can be added). Requires PET image and segment mask image. Returns ROI-level estimates for parameters in one result file and depending on selected model also curve fit plots. Optionally voxel-level models can be run. Logs for each ROI are returned so potential error and warnings are recorded.

The program assumes certain folder structure. Enviroment variable TOTAL_BODY_PET_DATA_DIR must be set correctly to point to a folder where subject folders are. Each subject folder must be in this format: getenv('TOTAL_BODY_PET_DATA_DIR')/subject/pet/pet_img.nii AND getenv('TOTAL_BODY_PET_DATA_DIR')/subject/anat/rsubject_segemntations.nii

Parameters:

  • subject (char array) – Subject ac-number or other identifier.

  • study_specs (struct) – Study specific information.

  • turbo_specs (struct) – Options for controlling TURBO behaviour such as verbose and parallel run.

  • modelling_options (struct) – Options for modelling, such as selecting model and bounds for fitting.

  • petfile (char array) – Full filepath to /your/pet/file.nii.

  • frametimes (Nx2 array) – Frame start and end times in an array.

  • inputdata (Mx2 array) – Input measure times and time activity curve.

  • tacdata (struct) – Must contain all tacs (roi_amount, frame_amount), roinames and roivolumes in same order.

  • resliced_ct_seg_file (char array) – Full filepath /your/ct/segmentation/image.nii where the CT image is resliced to same dimensions as PET image.

  • results_dir (char array) – Filepath to the folder where the results are saved in separate subfolders.

  • whole_pet_mask (Vx1 array, default: []) – Linear indices for a mask that contains all of the body with background filtered away.

Returns:

failed_roi_idx – List of failed ROI indices.

Return type:

array

Notes

There are two library options for doing the modelling, TPCCLIB https://gitlab.utu.fi/vesoik/tpcclib and Matlab implementations of the same modelling functions found in TPCCLIB. Matlab version is more memory safe for parallel run for H2O modelling. TPCCLIB has to load the whole image for voxel level modelling and running this in parallel takes a lot of RAM. Matlab implementation loads frame by frame only the relevant mask indices so it uses significantly less RAM (estimation is 1/frameamount RAM compared to TPCCLIB). For Patlak TPCCLIB is a lot faster than Matlab and uses the same amount of memory.