TURBO preprocessing functions

• calculate_best_ref_frame

• calculate_mc_startframe

• calculate_mc_startframe_after_tracerpeak

• compute_ncc

• extract_atlas_tac

• fbf_motion_correction

• greedy_apply_registration

• greedy_registration

• run_check_pet_ct_coreg

• run_falcon_mc

• run_greedy_ct_coreg

• run_greedy_fwd_deformation

• run_pet_fbf_motion_correction

• run_pet_motion_correction

• run_ROI_motion_correction

• totalbody_turbo_processor

• turbo_decay_correct_to_injection_time

• turbo_get_frame_string

• turbo_parse_frames_string

• turbo_read_specs

• turbo_write_specs

calculate_best_ref_frame(files, ct, maskidx, use_parfor)

calculate_mc_startframe(pet_nii_files, ref_frame, petmaskidx, greedy_dir, use_parfor)

calculate_mc_startframe_after_tracerpeak(pet, ct_segmentfile, roinames, frametimes)

compute_ncc(F, M, K, N, eps)

c3d_test:

extract_atlas_tac(Atlas, pet_img, atlas_label, frame_nr)

Extracts average TAC from 3D PET image using segmentation image (Atlas).

pet_img is SPM nifti object (pet_img = nifti(pet))

Parameters:

• Atlas (NIFTI object) – Atlas = nifti(segmentation_image.nii). Contains the segmentation data.

• pet_img (NIFTI object) – pet_img = nifti(pet.nii).

• atlas_label (int) – Label of the segment where the TAC is extracted.

• frame_nr (int) – PET frame where the TAC is extracted from.

Returns:

• tac (Nx1 double array) – Extracted TAC.

• roi_volume (double) – Volume of ROI in mm3.

fbf_motion_correction(petfile, ct_seg_file, result_dir, options)

Frame-by-frame motion correction for PET using segment image

PET frames are coregistered to segmentation image where the mask area stays the same but the mask value (label) is replaced with mean value inside the mask from each frame.

Either ctfile or warp_files need to be specified.

TODO make better description.

For better information about greedy parameters, visit https://greedy.readthedocs.io/en/latest/ or run line system([get_env(‘GREEDY_DIR’] filesep ‘greedy’).

Parameters:

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

• ct_seg_file (char array) – Full filepath to CT segmentation file, eg. /your/ct/seg_file.nii

• result_dir (char array) – Full path to the result folder where all the files are saved, eg. /my/result/folder/

• ctfile (char array) – Full filepath to CT file, eg. /your/ct/file.nii

• warp_files (Nx1 cell array) – Full filepathss to warp files. The warps are applied in the same order as they are in the list. Example list: {/your/affine/transdormation/file.mat; /your/elastic/warp/file.nii}

• verbose (int, default : 1) –

  • 0, nothing is printed to console (SPM may print something).

  • 1, informaion about program run is printed.

• dof (int, default : 6) –

  Degrees of freedom for affine registration. Possible values are:

  • 6, rigid (translation and rotation)

  • 7, rigid + uniform scaling

  • 12, affine (translation, rotation, scaling, shear)

• metric (char array, default : 'NCC 2x2x2') –

  Metric used in the registration. Possible values are:

  • SSD: sum of square differences (default)

  • MI: mutual information

  • NMI: normalized mutual information

  • NCC AxBxC: normalized cross-correlation

  • MAHAL: Mahalanobis distance to target warp

• iterations (char array, default : '100x25x10') – Number of iterations per level of multi-res. The example format is ‘100x25x10’.

• interp (char array, default : 'LINEAR') –

  Interpolation for the next pair. Possible values are

  • ’NN’

  • ’LINEAR*’

  • ’LABEL sigma’

• threads (int, default : 5) – Number of threads used for registration.

• registration_mode (char array, default : 'linear') –

  Possible values are ‘linear’, ‘nonlinear’, ‘both’.

  • ’linear’, linear transformation, dof 6, 7, or 12. Dof 6 and 7 are

  rigid transformations. - ‘nonlinear’, nonlinear registration. - ‘both’, first estimates movement using affine registration and after using nonlinear registration for finer details.

• padding (6x1 int array, default : [0,0,0,0,0,0]) – Padding for each dimension. After the bounding box is calculated, padding values are used to enlarge it in each dimension.

• start_frame (int, default : 1) – Starting frame for motion correction. Frames before this are excluded from motion correction.

Returns:

• result_files (cell array (5, 1)) – All result files in order they are created.

• warp_files (cell array) – Created warp files.

greedy_apply_registration(moving_image, reference_image, warp_files, result_file, options)

Applies greedy warp files to a .nii file

Parameters:

• moving_image (char array) – Registration is applied to this image.

• reference_image (char array) – Result image uses reference image space.

• warp_files ((:, 1) cell array) – List of all warps to be applied to the moving image. The list must be of type (:, 1) cell array, where each row contains one warp file path. The warps are applied from start to end to the moving image.

• result_file (char array) – Full path to the result file, eg. /my/result/file.nii

• interp (char array, default : 'LINEAR') –

  Interpolation for the next pair. Possible values are

  • ’NN’

  • ’LINEAR*’

  • ’LABEL sigma’

• threads (int, default : 5) – Number of threads used for registration.

greedy_registration(moving_image, reference_image, result_folder, options)

Greedy registration for moving image to reference image.

Wrapper for greedy registration to coregister moving image to reference image.

See more at: https://greedy.readthedocs.io/en/latest/.

WARNING! THE DOCUMENTATION HAS NOT BEEN UPDATED AND IS NOT UP TO DATE!

Parameters:

• moving_image (char array) – Registration is applied to this image.

• reference_image (char array) – Result image uses reference image space.

• result_folder (char array) – Full path to the result folder where all the files are saved, eg. /my/result/folder/

• dof (int, default : 6) –

  Degrees of freedom for affine registration. Possible values are:

  • 6, rigid (translation and rotation)

  • 7, rigid + uniform scaling

  • 12, affine (translation, rotation, scaling, shear)

• metric (char array, default : 'NCC 2x2x2') –

  Metric used in the registration. Possible values are:

  • SSD: sum of square differences (default)

  • MI: mutual information

  • NMI: normalized mutual information

  • NCC AxBxC: normalized cross-correlation

  • MAHAL: Mahalanobis distance to target warp

• iterations (char array, default : '100x25x10') – Number of iterations per level of multi-res. The example format is ‘100x25x10’.

• interp (char array, default : 'LINEAR') –

  Interpolation for the next pair. Possible values are

  • ’NN’

  • ’LINEAR*’

  • ’LABEL sigma’

• threads (int, default : 5) – Number of threads used for registration.

• registration_mode (char array, default : 'linear') –

  Possible values are ‘linear’, ‘nonlinear’, ‘both’.

  • ’linear’, linear transformation, dof 6, 7, or 12. Dof 6 and 7 are

  rigid transformations. - ‘nonlinear’, nonlinear registration. - ‘both’, first estimates movement using affine registration and after using nonlinear registration for finer details.

• additional_images ((:, 1) cell array) – The registration is also applied to this list of images. The list must be a (:,1) cell array where each row contains a filepath to a image that will be coregistered.

Returns:

• coregistered_image_files ((:, 1) cell array) – Cell array list of final coregistered images.

• warp_files ((:,1) cell array) – Warp files used in the registration.

run_check_pet_ct_coreg(meanpet, resliced_ct, resliced_ct_seg, roinames, qc_folder)

QC: PETmean vs CT-segments

run_falcon_mc()

add to settings

run_greedy_ct_coreg(ct_filename, meanpet_filename, segments, interp)

Add documentation here

run_greedy_fwd_deformation(greedyfolder, coreg_nii, reference_image, suffix, resultfolder, varargin)

run_pet_fbf_motion_correction(petfile, segfile, result_file, options)

Runs rigid motion correction for PET image

TODO add reference/link here

Parameters:

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

• seg_file (char array) – Full filepath to CT segmentation file, eg. /your/ct/seg_file.nii

• result_file (char array) – Motion corrected file, eg. /your/motion/corrected/image.nii

• verbose (int, default : 1) –

  • 0, nothing is printed to console (SPM may print something).

  • 1, informaion about program run is printed.

• dof (int, default : 6) –

  Degrees of freedom for affine registration. Possible values are:

  • 6, rigid (translation and rotation)

  • 7, rigid + uniform scaling

  • 12, affine (translation, rotation, scaling, shear)

• metric (char array, default : 'NCC 2x2x2') –

  Metric used in the registration. Possible values are:

  • SSD: sum of square differences (default)

  • MI: mutual information

  • NMI: normalized mutual information

  • NCC AxBxC: normalized cross-correlation

  • MAHAL: Mahalanobis distance to target warp

• iterations (char array, default : '100x25x10') – Number of iterations per level of multi-res. The example format is ‘100x25x10’.

• interp (char array, default : 'LINEAR') –

  Interpolation for the next pair. Possible values are

  • ’NN’

  • ’LINEAR*’

  • ’LABEL sigma’

• threads (int, default : 5) – Number of threads used for registration.

• registration_mode (char array, default : 'linear') –

  Possible values are ‘linear’, ‘nonlinear’, ‘both’.

  • ’linear’, linear transformation, dof 6, 7, or 12. Dof 6 and 7 are

  rigid transformations. - ‘nonlinear’, nonlinear registration. - ‘both’, first estimates movement using affine registration and after using nonlinear registration for finer details.

• start_frame (int, default : 1) – Starting frame for motion correction. Frames before this are excluded from motion correction.

run_pet_motion_correction(pet, petmaskidx, ctfile, segfile, frametimes, roinames, petfolder_mc, use_ncc, use_parfor, verbose)

runs pet motion correction using diffeomorphic greedy coregistration algorithm & coregisters ct to motion corrected pet sum using diffeomorphic greedy

run_ROI_motion_correction(subject, frametimes, roinames, roiname_qc_list, ref_frame, meanpet, ct_seg, greedy_transformations_dir, qc_results_dir, use_parfor, verbose)

totalbody_turbo_processor(subject, pet_file, ct_orig_file, turbo_options, frametimes, use_ncc, qc_dir)

Preprocess PET and CT image for modelling

Runs moton correction, CT segmentation and automatic input function extraction.

Motion correction is implemented by FALCON toolbox ENHANCE-PET/FALCON. Using this is optional, but it may help if there is a lot of motion in the PET image between frames.

Segmentation is implemented by TotalSegmentator wasserth/TotalSegmentator, https://pubs.rsna.org/doi/10.1148/ryai.230024. This creates 104 ROIs from the CT image. These ROIs are used to get bodypart specific parameter estimates later.

Aorta and myocardium segmentations are used to determine input function automatically. Mean TACs are also gathered from all segmented ROIs. Results are saved to subject_pet_tacdata.mat file.ref_frame turbo_options should contain the following fields:

• use_parfor : (always necessary, default=0)

• run_preprocessing : 1

• use_highres_segmentation : 1

• use_elastic_mc : 1

• run_qc : 1

• extract_ROIs : 1

• run_modelling : 1

• run_magia : 1

• use_IDIFcoregister : 0

• crop_brains : 1

• ref_frame : 12

• verbose : 0

• debug : 0

• rethrow_error : 0

Parameters:

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

• pet_file (char array) – Full path to PET file, eg. /path/to/your/pet.nii.

• ct_orig_file (char array) – Full path to CT file, eg. /path/to/your/ct.nii.

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

• frametimes (Nx2 double array) – Frametimes of PET image.

• use_ncc (logical) – Used for determining starting frame for motion correction.

• qc_dir (char array) – Full path to quality control directory, eg. /path/to/your/quality_control/.

Returns:

• result_pet_file (char array) – Path to result PET file, eg. /path/to/result/pet.nii.

• result_ct_file (char array) – Path to result CT file, eg. /path/to/result/ct.nii.

• result_ct_seg_file (char array) – Path to result CT segmentations file, eg. /path/to/result/ct_segmentations.nii.

• turbo_options (struct) – TURBO estimates values for a few parameters during the run. These are updated to the options struct. The following parameters are defined:

  • rigid_mc_start_frame : start rigid moton correction from this

  frame forward . - elastic_mc_start_frame : start elastic motion correction from this frame forward . - mc_ref_frame : reference frame used for motion correction; other frames are corrected to this frame.

• warp_file_dirs (2x1 cell array) – Directories for coregister warps to original pet image and motion corrected pet image, if those were run.

  • warp_file_dirs{1} is directory for coregistration warps of ct to

  original pet image. - warp_file_dirs{2} is directory for coregistration warps of ct to motion ocrrected pet image.

Notes

Full high resolution segmentation is very slow without GPU. With GPU processing time is couple of minutes and with CPU the same takes 4+ hours. If you don’t have GPU, set turbo_options.use_highres_segmentation = 0. This makes the segmentation faster but poorer quality.

turbo_decay_correct_to_injection_time(pet_file, frames, tracer)

frames contains times since injection

turbo_get_frame_string(frames)

turbo_parse_frames_string(frame_string)

turbo_read_specs(specs_file)

Reads the specifications from the specs.txt file and modelling_options.txt file

turbo_write_specs(specs, specs_file)