GraphicalAnalysisParametricImage

class petpal.kinetic_modeling.parametric_images.GraphicalAnalysisParametricImage(input_tac_path: str, input_image_path: str, output_directory: str, output_filename_prefix: str)

Class for generating parametric images of 4D-PET images using graphical analyses. It provides methods to run graphical analysis, calculate properties of the resulting images, and save the results using file paths.

Variables:

• input_tac_path (str) – Absolute path to the input Time-Activity Curve (TAC) file.

• input_image_path (str) – Absolute path to the 4D PET image file.

• output_directory (str) – Absolute path to the output directory.

• output_filename_prefix (str) – Prefix of the output file names.

• analysis_props (dict) – Dictionary of properties of the graphical analysis.

• slope_image (np.ndarray) – The slope image resulting from the graphical analysis, initialized to None.

• intercept_image (np.ndarray) – The intercept image resulting from the graphical analysis, initialized to None.

Initializes the GraphicalAnalysisParametricImage with the specified parameters.

This method initializes necessary attributes for the GraphicalAnalysisParametricImage object with the provided arguments. It sets the absolute file paths for the input TAC, 4D PET image, and output directory, and initializes the analysis properties. Further, it initializes variables for the slope and intercept images.

Parameters:

• input_tac_path (str) – Path to the input Time-Activity Curve (TAC) file.

• input_image_path (str) – Path to the 4D PET image file.

• output_directory (str) – Path to the destination directory where output files will be saved.

• output_filename_prefix (str) – Prefix to use for the names of the output files.

Returns:

None

init_analysis_props()

Initializes the analysis properties dictionary.

The analysis properties dictionary contains properties derived from the analysis. It begins with certain known values, such as file paths, but most values are initialized to None and filled in later as the analysis is performed.

Properties include:

• FilePathPTAC (str): The path to the input Time-Activity Curve (TAC) file.

• FilePathTTAC (str): The path to the 4D PET image file.

• MethodName (str): The name of the graphical analysis method used, to be filled in later.

• ImageDimensions (tuple): The dimensions of the images resulting from the analysis, to be filled in later.

• StartFrameTime (float): The start time of the frame used in the analysis, filled in after the analysis.

• EndFrameTime (float): The end time of the frame used in the analysis, filled in after the analysis.

• ThresholdTime (float): The time threshold used in the analysis, filled in after the analysis.

• RunKwargs (dict): Keyword arguments passed on to the analysis function.

• NumberOfPointsFit (int): The number of points fitted in the analysis, filled in after the analysis.

• SlopeMaximum (float): The maximum slope found in the analysis, filled in after the analysis.

• SlopeMinimum (float): The minimum slope found in the analysis, filled in after the analysis.

• SlopeMean (float): The mean of the slopes found in the analysis, filled in after the analysis.

• SlopeVariance (float): The variance of the slopes found in the analysis, filled in after the analysis.

• InterceptMaximum (float): The maximum intercept found in the analysis, filled in after the analysis.

• InterceptMinimum (float): The minimum intercept found in the analysis, filled in after the analysis.

• InterceptMean (float): The mean of the intercepts found in the analysis, filled in after the analysis.

• InterceptVariance (float): The variance of the intercepts found in the analysis, filled in after the analysis.

Returns:

props (dict) – The initialized properties dictionary.

run_analysis(method_name: str, t_thresh_in_mins: float, **run_kwargs)

Executes the complete analysis procedure.

This method orchestrates the full analysis by orchestrating the calculation of parametric images, as well as compiling the properties related to the analysis. Both are determined based on the provided method name and the threshold time.

Parameters:

• method_name (str) – The name of the methodology adopted for the process.

• t_thresh_in_mins (float) – The threshold time used through the analysis (in minutes).

• run_kwargs – Additional keyword arguments passed on to calculate_parametric_images() and calculate_analysis_properties().

See also

• calculate_parametric_images()

• calculate_analysis_properties()

Returns:

None

save_analysis()

Stores the results from an analysis routine.

This method executes the storage of parametric images, as well as the properties related to the analysis. It assumes that the method ‘run_analysis’ is called before this method.

Raises:

RuntimeError – If the method ‘run_analysis’ is not called before this method.

See also

• save_parametric_images()

• save_analysis_properties()

Returns:

None

calculate_analysis_properties(method_name: str, t_thresh_in_mins: float, **run_kwargs)

Performs a set of calculations to collate various analysis properties.

This method orchestrates the calculation of properties related to both the parametric images and the fitting process. It does this by calling calculate_parametric_images_properties() and calculate_fit_properties() respectively.

Parameters:

• method_name (str) – The name of the method used for the fitting process.

• t_thresh_in_mins (float) – The threshold time (in minutes) used for the fitting process.

• run_kwargs – Additional keyword arguments passed on to calculate_fit_properties().

See also

• calculate_parametric_images_properties()

• calculate_fit_properties()

Returns:

None. The results are stored within the instance’s analysis_props variable.

calculate_fit_properties(method_name: str, t_thresh_in_mins: float, **run_kwargs)

Calculates and stores the properties related to the fitting process.

This method calculates several properties related to the fitting process, including the threshold time, the name of the method used, the start and end frame time, and the number of points used in the fit. These values are stored in the instance’s analysis_props variable.

Parameters:

• method_name (str) – The name of the methodology adopted for the fitting process.

• t_thresh_in_mins (float) – The threshold time (in minutes) used in the fitting process.

• run_kwargs – Additional keyword arguments used in the analysis. These are saved to the analysis properties as individual properties.

Note

This method relies on the safe_load_tac() function to load time-activity curve (TAC) data from the file at self.input_tac_path, and the petpal.graphical_analysis.get_index_from_threshold() function to get the index from the threshold time.

See also

• safe_load_tac(): Function to safely load TAC data from a file.

• petpal.graphical_analysis.get_index_from_threshold(): Function to get the index

  from the threshold time.

Returns:

None. The results are stored within the instance’s analysis_props variable.

calculate_parametric_images_properties()

Initiates the calculation of properties for parametric images.

This method triggers the calculation of statistical properties for slope and intercept images. Additionally, it captures the shape of the slope image as the ‘ImageDimensions’ and stores it in analysis_props.

Note

You should ensure the slope_image attribute has been correctly set before calling this method. This means that run_analysis has already been called.

See also

calculate_slope_image_properties: Method to calculate various statistics for slope

image.

calculate_intercept_image_properties: Method to calculate various statistics for

intercept image.

Returns:

None. The results are stored within the instance’s analysis_props variable.

calculate_slope_image_properties()

Calculates and stores statistical properties of the slope image.

This method calculates the maximum, minimum, mean, and variance of the slope_image attribute, and stores these values in the analysis_props dictionary.

The keys in analysis_props for these values are: SlopeMaximum, SlopeMinimum, SlopeMean, and SlopeVariance, respectively.

Note

You should ensure the slope_image attribute has been correctly set before calling this method.

No explicit return value. The results are stored within the instance’s analysis_props variable.

calculate_intercept_image_properties()

Calculates and stores statistical properties of the intercept image.

This method calculates the maximum, minimum, mean, and variance of the intercept_image attribute, and stores these values in the analysis_props dictionary.

The keys in analysis_props for these values are: InterceptMaximum, InterceptMinimum, InterceptMean, and InterceptVariance, respectively.

Note

You should ensure the intercept_image attribute has been correctly set before calling this method.

No explicit return value. The results are stored within the instance’s analysis_props variable.

calculate_parametric_images(method_name: str, t_thresh_in_mins: float, **run_kwargs)

Performs graphical analysis of PET parametric images and generates/updates the slope and intercept images.

This method uses the given graphical analysis method and threshold to perform the analysis given the input Time Activity Curve (TAC) and 4D PET image, and updates the slope and intercept images accordingly. PET images are loaded from the specified path. Then, the parametric images are calculated using the specified graphical method and threshold time by explicitly analyzing each voxel in the 4D PET image.

Parameters:

• method_name (str) – The name of the graphical analysis method to be used.

• t_thresh_in_mins (float) – The threshold time in minutes.

• run_kwargs – Additional keyword arguments passed on to generate_parametric_images_with_graphical_method().

Returns:

None

Raises:

• Exception – An error occurred during the graphical analysis. This could be due to an

• invalid method name or incorrect inputs to the method. –

See also

• generate_parametric_images_with_graphical_method()

• petpal.graphical_analysis.patlak_analysis()

• petpal.graphical_analysis.logan_analysis()

• petpal.graphical_analysis.alternative_logan_analysis()

__call__(method_name, t_thresh_in_mins, **run_kwargs)

save_parametric_images()

Saves the slope and intercept images as NIfTI files in the specified output directory.

This method generates and saves two NIfTI files: one for the slope image and one for the intercept image. It uses the output directory and filename prefix provided during instantiation of the class, along with the analysis method name, to generate a filename prefix for both images. The filenames follow the patterns {output_filename_prefix}-parametric-{method}-slope.nii.gz and {output_filename_prefix}-parametric-{method}-intercept.nii.gz respectively. The affine transformation matrix for the new NIfTI images is derived from the original 4D PET image.

Parameters:

None

Returns:

None

Raises:

• IOError – An error occurred accessing the output_directory or while writing to the NIfTI

• file. –

save_analysis_properties()

Saves the analysis properties to a JSON file in the output directory.

This method involves saving a dictionary of analysis properties, which include file paths, analysis method, start and end frame times, threshold time, number of points fitted, and various properties like the maximum, minimum, mean, and variance of slopes and intercepts found in the analysis. These analysis properties are written to a JSON file in the output directory with the name following the pattern {output_filename_prefix}-analysis-props.json.

Parameters:

None

Returns:

None

Raises:

• IOError – An error occurred accessing the output_directory or while writing to the JSON

• file. –

See also

• save_analysis_properties()