Modelling functions#

fit_fur
fit_h2o
fit_logan
fit_patlak
fit_suv
fitdelay
imgflow_nifti_mask
imgfur
imglogan
imgsuv
interpolate_optimized
lsqnonneg_optimized
nnls2_2tcm
simC3vs

fit_fur(frametimes, TACs, inputdata, start_time, end_time, glucose, ic)#

Calculates FUR for all curves in TACs.

Calculates FUR for all curves in TACs. Calculates FUR for all curves in TACs. Calculates FUR for all curves in TACs. Calculates FUR for all curves in TACs. Calculates FUR for all curves in TACs. Calculates FUR for all curves in TACs.

Parameters:

frametimes (2xN array) – Frame start and end times in an array.
TACs (VxN array) – List of time activity curves to be modelled.
inputdata (2xM array) – Input measure times and time activity curve.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.
glucose (double) – Glucose uptake value.
ic (double) – ic value.

Returns:

List of FUR parameter fits.

Return type:

Vx1 array

Notes

N is the amount of frames for tissue data and M is the amount of frames for plasma data.

fit_h2o(frametimes, tissue_curve, input_times, ca, cb, f, fa, n_iter, varargin)#

Non-linear fit that estimates 1-tissue compartmental model parameters K1, K1/k2, Va and delay.

Parameters:

frametimes (2xN array) – Frame start and end times in an array.
tissue_curve (1xN array) – Time activity curve of tissue.
input_times (1xM array) – Time points for plasma data.
ca (1xM array) – Array of arterial plasma activities.
cb (1xM array) – Array of arterial blood activities.
f (double) – Blood flow; if 0, function assumes that f>>k1, and Cvb=Cab.
fa (double) – Arterial fraction of vascular volume.
n_iter (int) – Iteration count for repeating the fitting.
varargin{1} (4x1 array) – Lower bound for parameters in order [K1, K1/k2, Va, delay].
varargin{2} (4x1 array) – Upper bound for parameters in order [K1, K1/k2, Va, delay].

Returns:

y (array) – Estimated curve
x_optim (4x1 array) – Estimated parameters as an array.
flow (double) – Estimation of flow parameter.
resnorm (double) – Resnorm error from lsqcurvefit().
Residual (double) – Sum of absolute errors between each timepoint.

Notes

Original waterFunc code can be found at: https://gitlab.utu.fi/vesoik/tpcclib/-/blob/c6b5d488636dc92fde8b3ddbba9a59bfe68883c9/v1/cmfits/fit_h2o.c

Fit is performed using Matlab’s lsqcurvefit https://se.mathworks.com/help/optim/ug/lsqcurvefit.html for n_iter times and the lowest error is selected. Bounds for the optimizer (k1, k2, vb, delay time)

fit_logan(frametimes, TACs, inputdata, start_time, end_time)#

Fit logan curve to PET TACs

Parameters:

frametimes (2xN array) – Frame start and end times in an array.
TACs (VxN array) – List of time activity curves to be modelled. Curves are in rows.
inputdata (2xM array) – Input measure times and time activity curve.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.

Returns:

Vt (Vx1 array) – List of Vt parameter fits.
intercept (Vx1 array) – List of intercept parameter fits.
x (VxN array) – Input integral / input
y (VxN array) – ROI tac / input
k (array) – Timepoints corresponding to the fit.

Notes

N is the amount of frametimes for tissue data and M is the amount of frametimes for plasma data.

May use a lot of memory for large TAC arrays.

fit_patlak(frametimes, tacs, plasmadata, start_time, end_time)#

Fits Patlak to the given time-activity curves (tacs).

Parameters:

frametimes (2xN array) – Frame start and end times in an array.
tacs (VxN array) – List of time activity curves to be modelled.
inputdata (2xM array) – Input measure times and time activity curve.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.

Returns:

Ki (Vx1 array) – Ki estimate for each time activity curve in tacs.
intercept (Vx1 array) – intercept estimate for each time activity curve in tacs.
patlak_x – Input integral / input
patlak_Y – ROI tac / input
k (array) – Timepoints corresponding to the fit.

Notes

tacs can contain multiple time activity curves.

fit_suv(frametimes, TACs, start_time, end_time, dose, weight)#

Calculates SUV for all curves in TACs.

Parameters:

frametimes (2xN array) – Frame start and end times in an array.
TACs (VxN array) – List of time activity curves to be modelled. Curves are in rows.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.
weight (double) – Weight of the subject.
dose (double) – Given dose to the subject.

Returns:

List of SUV parameter fits.

Return type:

Vx1 array

Notes

N is the amount of frames for tissue data and M is the amount of frames for plasma data.

fitdelay(frametimes, tissue_curve, inputdata, model, options)#

Finds the best delay time for input curve

Uses NNLS to determine the best shift for input curve. Input curve is shifted from -60s to 60s in 1 second intervals and then that curve is fitted to the data. The smallest error is selected as the returned delay.

Parameters:

frametimes (2xN array) – Frame start and end times in an array.
tissue_curve (1xN array) – Time activity curve to be modelled.
inputdata (2xM array) – Input measure times and time activity curve.
model (int) – Used model. Must be 1 or 2.
fit_length (double, default: frametimes(end, 2)) – Consider only interval [0, fit_length] from tissue curve. This is equal to tissue_curve(tissue_curve <= fit_length). Must be in seconds.
interval (2x1 array, default: [-60, 60]) – Defines the interval where fits are done.
timestep (double, default: 1) – Timesteps between each fit.
verbose (int, default: 0) – Verbose level for printing information during progrma run. 0 to omit printing.

Returns:

best_model_curve (array) – Modelled tissue curve using the optimal delay.
delay_corrected_inputdata (array) – Input times and curve that was used for the best delay fit.
delay (double) – The delay that produced smallest error for the fit.
best_params (3x1 or 5x1 array) – Array containing the estimated P-parameters.

Notes

This code is based on codes by Vesa Oikonen: http://www.turkupetcentre.net/tpcclib-doc/v1/fitdelay_8c_source.html

imgflow_nifti_mask(petfile, frametimes, inputdata, mask_idx, options)#

Does voxel level modelling within a mask for radiowater PET image.

For reliable results, inputdata should be delay corrected

Parameters:

petfile (char array) – Full path to the petfile e.g. /your/path/to/petimg.nii
frametimes (2xN array) – Frame start and end times in an array.
inputdata (2xM array) – Input measure times and time activity curve.
mask_idx (array) – Logical array or linear index list containing the mask.
fit_length (double, default: frametimes(end, 2)) – Include only TAC from 0 to fit_length (H2O only).
verbose (int, default: 0) – Verbose level for printing information during progrma run. 0 to omit printing.
nnls_print_index (int, default: 0) – Prints the nnls matrix of this voxel. Used for debugging. The value is linear index in respect of the whole image dimensions.
filename (char array, default: []) –
Basename for the output images if needed. Images are saved like:

filename = /your/path/to/img, filename_imgflowm_K1.nii etc.

Returns:

K1 (array) – K1 values corresponding to the mask_idx. K1(1) corresponds to the pet_img_3d(mask_idx(1)) K1 estimate.
k2 (array) – k2 values, similar system as with K1.
Va (array) – Va values, similar system as with K1.

imgfur(petfile, frametimes, inputdata, mask_idx, start_time, end_time, glucose, ic, options)#

Calculates FUR image for PET image inside a specified mask.

Parameters:

petfile (string) – Full filepath to the pet file.
frametimes (2xN array) – Frame start and end times in an array.
inputdata (2xM array) – Input measure times and time activity curve.
mask_idx (Vx1 array) – Linear indices of all the voxels that are modelled.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.
glucose (double) – Glucose uptake value.
ic (double) – ic value.
verbose (int, default=0) – Verbose level to print information on program run.

Returns:

fur – Corresponding FUR fits to mask_idx voxels.

Return type:

Vx1 array

Todo

Implement more memory safe version for big masks.

imglogan(petfile, frametimes, inputdata, mask_idx, start_time, end_time, options)#

Does voxel level Logan-modelling within a mask for FDG PET image.

Parameters:

petfile (char array) – Full path to the petfile e.g. /your/path/to/petimg.nii
frametimes (2xN array) – Frame start and end times in an array.
inputdata (2xM array) – Input measure times and time activity curve.
mask_idx (array) – Logical array or linear index list containing the mask.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.
verbose (int, default: 0) – Verbose level for printing information during progrma run. 0 to omit printing.
filename (char array, default: []) –
Basename for the output images if needed. Images are saved like:

filename = /your/path/to/img, filename_imgflowm_Ki.nii etc.

Returns:

Vt (array) – K1 values corresponding to the mask_idx. Ki(1) corresponds to the pet_img_3d(mask_idx(1)) K1 estimate. mask_idx is in linear index format.
intercept (array) – Intercept values, similar system as with Ki.

imgsuv(petfile, frametimes, mask_idx, start_time, end_time, dose, weight, options)#

Calculates SUV image for PET image inside a specified mask.

Parameters:

petfile (string) – Full filepath to the pet file.
frametimes (2xN array) – Frame start and end times in an array.
mask_idx (Vx1 array) – Linear indices of all the voxels that are modelled.
start_time (double) – Start modelling after this timepoint.
end_time (double) – End modelling at this timepoint.
weight (double) – Weight of the subject.
dose (double) – Given dose to the subject.
verbose (int, default=0) – Verbose level to print information on program run.

Returns:

fur – Corresponding FUR fits to mask_idx voxels.

Return type:

Vx1 array

Todo

Implement more memory safe version for big masks.

interpolate_optimized(x, y, newx)#: from interpolate.c to interpolate curve to new timepoints

lsqnonneg_optimized(C, d, options, varargin)#

LSQNONNEG Linear least squares with nonnegativity constraints. X = LSQNONNEG(C,d) returns the vector X that minimizes NORM(d-C*X) subject to X >= 0. C and d must be real.

X = LSQNONNEG(C,d,OPTIONS) minimizes with the default optimization parameters replaced by values in the structure OPTIONS, an argument created with the OPTIMSET function. See OPTIMSET for details. Used options are Display and TolX. (A default tolerance TolX of 10*MAX(SIZE(C))*NORM(C,1)*EPS is used.)

X = LSQNONNEG(PROBLEM) finds the minimum for PROBLEM. PROBLEM is a structure with the matrix ‘C’ in PROBLEM.C, the vector ‘d’ in PROBLEM.d, the options structure in PROBLEM.options, and solver name ‘lsqnonneg’ in PROBLEM.solver.

[X,RESNORM] = LSQNONNEG(…) also returns the value of the squared 2-norm of the residual: norm(d-C*X)^2.

[X,RESNORM,RESIDUAL] = LSQNONNEG(…) also returns the value of the residual: d-C*X.

[X,RESNORM,RESIDUAL,EXITFLAG] = LSQNONNEG(…) returns an EXITFLAG that describes the exit condition. Possible values of EXITFLAG and the corresponding exit conditions are

1 LSQNONNEG converged with a solution X. 0 Iteration count was exceeded. Increasing the tolerance

(OPTIONS.TolX) may lead to a solution.

[X,RESNORM,RESIDUAL,EXITFLAG,OUTPUT] = LSQNONNEG(…) returns a structure OUTPUT with the number of steps taken in OUTPUT.iterations, the type of algorithm used in OUTPUT.algorithm, and the exit message in OUTPUT.message.

[X,RESNORM,RESIDUAL,EXITFLAG,OUTPUT,LAMBDA] = LSQNONNEG(…) returns the dual vector LAMBDA where LAMBDA(i) <= 0 when X(i) is (approximately) 0 and LAMBDA(i) is (approximately) 0 when X(i) > 0.