weighted_series_sum#

petpal.utils.useful_functions.weighted_series_sum(input_image_path: str, out_image_path: str, half_life: float, verbose: bool = False, start_time: float = 0, end_time: float = -1) → numpy.ndarray#

Sum a 4D image series weighted based on time and re-corrected for decay correction.

First, a scaled image is produced by multiplying each frame by its length in seconds, and dividing by the decay correction applied:

\[f_i'=f_i\times \frac{t_i}{d_i}\]

Where \(f_i,t_i,d_i\) are the i-th frame, frame duration, and decay correction factor of the PET series. This scaled image is summed over the time axis. Then, to get the output, we multiply by a factor called total decay and divide by the full length of the image:

\[d_{S} = \frac{\lambda*t_{S}}{(1-\exp(-\lambda*t_{S}))(\exp(\lambda*t_{0}))}\]
\[S(f) = \sum(f_i') * d_{S} / t_{S}\]

where \(\lambda=\log(2)/T_{1/2}\) is the decay constant of the radio isotope, \(t_0\) is the start time of the first frame in the PET series, the subscript \(S\) indicates the total quantity computed over all frames, and \(S(f)\) is the final weighted sum image.

# TODO: Determine half_life from .json rather than passing as argument.

Parameters:

  • input_image_path (str) – Path to a .nii or .nii.gz file containing a 4D PET image on which the weighted sum is calculated. Assume a metadata file exists with the same path and file name, but with extension .json, and follows BIDS standard.

  • out_image_path (str) – Path to a .nii or .nii.gz file to which the weighted sum is written. If none, will not write output to a file.

  • half_life (float) – Half life of the PET radioisotope in seconds.

  • verbose (bool) – Set to True to output processing information. Default is False.

  • start_time (float) – Time, relative to scan start in seconds, at which calculation begins. Must be used with end_time. Default value 0.

  • end_time (float) – Time, relative to scan start in seconds, at which calculation ends. Use value -1 to use all frames in image series. If equal to start_time, one frame at start_time is used. Default value -1.

Returns:

np.ndarray –

3D image array, in the same space as the input, with the weighted sum

calculation applied.

Raises:

ValueError – If half_life is zero or negative.

On this page

This Page