RTMAnalysis

class petpal.kinetic_modeling.rtm_analysis.RTMAnalysis(ref_tac_path: str, roi_tac_path: str, output_directory: str, output_filename_prefix: str, method: str)

A class designed to carry out various Reference Tissue Model (RTM) analyses on Time Activity Curves (TACs).

This class eases the process of conducting RTM analysis on TACs. Paths to both reference and region-of-interest (ROI) TACs are taken as inputs at initialization. The class further provides multiple utility functions for initializing and running the RTM analysis, and also for validating the inputs based on the RTM method chosen.

This class currently supports various RTM methods such as :’srtm’, ‘frtm’, ‘mrtm-original’, ‘mrtm’, and ‘mrtm2’.

Variables:

• ref_tac_path (str) – Absolute path for reference TAC

• roi_tac_path (str) – Absolute path for ROI TAC

• output_directory (str) – Absolute path for the output directory

• output_filename_prefix (str) – Prefix for the output filename of the result

• method (str) – RTM analysis method. Converts to lower case at initialization.

• analysis_props (dict) – Analysis properties dictionary initialized with method-specific property keys and default values.

• _has_analysis_been_run (bool) – Flag representing if the RTM analysis has been run to ensure correct order of operations.

Example

In the proceeding example, we assume that we have two tacs: a reference region tac, and a region of interest (ROI) tac named ‘ref_tac.txt’ and ‘roi_tac.txt’, respectively. Furthermore, we assume that both TACs are sampled at the same times, and are evenly sampled with respect to time.

import numpy as np
from petpal.kinetic_modeling.rtm_analysis as pet_rtms

file_rtm = pet_rtms.RTMAnalysis(ref_tac_path="ref_tac.txt",
                                roi_tac_path="roi_tac.txt",
                                output_directory="./",
                                output_filename_prefix='pre',
                                method="mrtm")
file_rtm.run_analysis(t_thresh_in_mins=40.0)
file_rtm.save_analysis()

See also

• FitTACWithRTMs: a class for analyzing TACs with RTMs.

Initialize RTMAnalysis with provided arguments.

The init method executes the following operations:

1. It converts the provided analysis method to lower case for consistency in internal

   processing.

2. It obtains the absolute paths for reference and ROI TAC files and the output

   directory, to ensure they are consistently accessible.

3. It initializes the analysis properties dictionary using init_analysis_props method.

4. It initializes the _has_analysis_been_run flag to False, to indicate that the RTM

   analysis has not yet been run.

Parameters:

• ref_tac_path (str) – Path to the file containing reference TAC.

• roi_tac_path (str) – Path to the file containing ROI TAC.

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

• output_filename_prefix (str) – Prefix that will be used for the output filename.

• method (str) – The RTM analysis method to be used. Could be one of ‘srtm’, ‘frtm’, ‘mrtm-original’, ‘mrtm’ or ‘mrtm2’.

init_analysis_props(method: str) → dict

Initializes the analysis properties dict based on the specified RTM analysis method.

Parameters:

method (str) – RTM analysis method. Must be one of ‘srtm’, ‘frtm’, ‘mrtm-original’, ‘mrtm’ or ‘mrtm2’.

Returns:

dict – A dictionary containing method-specific property keys and default values.

Raises:

ValueError – If input method is not one of the supported RTM methods.

run_analysis(bounds: None | numpy.ndarray = None, t_thresh_in_mins: float = None, k2_prime: float = None, **tac_load_kwargs)

Runs the full RTM analysis process which involves validating inputs, calculation fits, and deducing fit properties.

Specifically, it executes the following sequence:

1. validate_analysis_inputs()

2. calculate_fit()

3. calculate_fit_properties()

Parameters:

• bounds (Union[None, np.ndarray], optional) – Optional boundaries for parameters for fitting function.

• t_thresh_in_mins (float, optional) – Threshold time in minutes for the MRTM analyses.

• k2_prime (float, optional) – Input for the modified RTM (MRTM2, FRTM2, and SRTM2) analyses.

Returns:

None

validate_analysis_inputs(k2_prime, t_thresh_in_mins)

Validates the provided inputs for the RTM analysis.

If MRTM type of analysis is being run, it ensures that t_thresh_in_mins is not None. If modified analysis is being done (MRTM2, FRTM2, SRTM2), it ensures k2_prime is not None.

Parameters:

• k2_prime (float) – k2 prime value.

• t_thresh_in_mins (float) – Threshold time for MRTM analyses.

Raises:

ValueError – If an input required for the selected method is None.

calculate_fit(bounds: None | numpy.ndarray = None, t_thresh_in_mins: float = None, k2_prime: float = None)

Calculates the model fitting parameters for TACs using the chosen RTM analysis method.

This method executes the following sequence:

1. validate_analysis_inputs()

2. safe_load_tac() for both reference and ROI TACs

3. Creates a FitTACWithRTMs instance and fits TAC to the model

Parameters:

• bounds (Union[None, np.ndarray]) – Boundaries for parameters for fitting function.

• t_thresh_in_mins (float) – Threshold time for MRTM analyses.

• k2_prime (float) – k2 prime value.

• tac_load_kwargs (Any) – Additional keyword arguments for the loading TAC function.

Returns:

FitResults – Object containing fit results.

calculate_fit_properties(fit_results: numpy.ndarray | tuple[numpy.ndarray, numpy.ndarray], t_thresh_in_mins: float = None, k2_prime: float = None)

Calculates additional fitting properties based on the raw fit results.

It delegates the calculation to method-specific functions:

1. For ‘srtm’ or ‘frtm’ methods: _calc_frtm_or_srtm_fit_props() is used.

2. For ‘mrtm’ methods: _calc_mrtm_fit_props() is used.

Parameters:

• fit_results (Union[np.ndarray, tuple[np.ndarray, np.ndarray]]) – The fit results.

• t_thresh_in_mins (float) – Threshold time for MRTM analyses.

• k2_prime (float) – k2 prime value for ‘mrtm’ based methods.

Returns:

None

save_analysis()

Save the analysis results in JSON format.

The results are only saved if the analysis has been run (_has_analysis_been_run flag is checked).

Raises:

RuntimeError – If the :meth:’run_analysis’ method has not been called yet.

__call__(bounds, t_thresh_in_mins, k2_prime)

_calc_mrtm_fit_props(fit_results: numpy.ndarray | tuple[numpy.ndarray, numpy.ndarray], k2_prime: float, t_thresh_in_mins: float, props_dict: dict, write_simulated: bool = False)

Internal function used to calculate additional fitting properties for ‘mrtm’ type analyses.

This method is used internally within calculate_fit_properties().

Parameters:

• fit_results (np.ndarray) – Resulting fit parameters.

• k2_prime (float) – k2 prime value for ‘mrtm’ based methods.

• t_thresh_in_mins (float) – Threshold time for MRTM analyses.

_calc_frtm_or_srtm_fit_props(fit_results: tuple[numpy.ndarray, numpy.ndarray], k2_prime: float, props_dict: dict)

Internal function used to calculate additional fitting properties for ‘frtm’ and ‘srtm’ type analyses.

This method is used internally within calculate_fit_properties().

Parameters:

fit_results (tuple[np.ndarray, np.ndarray]) – Tuple containing the fit parameters and their corresponding fit covariances.

static _get_pretty_srtm_fit_param_vals(param_fits: numpy.ndarray, reduced: bool = False) → dict

Utility function to get nicely formatted fit parameters for ‘srtm(2)’ analysis.

Returns a dictionary with keys: ‘R1’, ‘k2’, and ‘BP’ and the corresponding values from param_fits.

Parameters:

param_fits (np.ndarray) – array containing the fit parameters.

Returns:

dict – Dictionary of fit parameters and their corresponding values.

static _get_pretty_frtm_fit_param_vals(param_fits: numpy.ndarray, reduced: bool = False) → dict

Utility function to get nicely formatted fit parameters for ‘frtm(2)’ analysis.

Returns a dictionary with keys: ‘R1’, ‘k2’, ‘k3’, and ‘k4’ and the corresponding values from param_fits.

Parameters:

param_fits (np.ndarray) – array containing the fit parameters.

Returns:

dict – Dictionary of fit parameters and their corresponding values.