RTMAnalysis ================================================ .. py: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'. :ivar ref_tac_path: Absolute path for reference TAC :vartype ref_tac_path: str :ivar roi_tac_path: Absolute path for ROI TAC :vartype roi_tac_path: str :ivar output_directory: Absolute path for the output directory :vartype output_directory: str :ivar output_filename_prefix: Prefix for the output filename of the result :vartype output_filename_prefix: str :ivar method: RTM analysis method. Converts to lower case at initialization. :vartype method: str :ivar analysis_props: Analysis properties dictionary initialized with method-specific property keys and default values. :vartype analysis_props: dict :ivar _has_analysis_been_run: Flag representing if the RTM analysis has been run to ensure correct order of operations. :vartype _has_analysis_been_run: bool .. rubric:: 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. .. code-block:: python 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() .. seealso:: * :class:`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. :param ref_tac_path: Path to the file containing reference TAC. :type ref_tac_path: str :param roi_tac_path: Path to the file containing ROI TAC. :type roi_tac_path: str :param output_directory: Path to the directory where the output will be saved. :type output_directory: str :param output_filename_prefix: Prefix that will be used for the output filename. :type output_filename_prefix: str :param method: The RTM analysis method to be used. Could be one of 'srtm', 'frtm', 'mrtm-original', 'mrtm' or 'mrtm2'. :type method: str .. py:method:: init_analysis_props(method: str) -> dict Initializes the analysis properties dict based on the specified RTM analysis method. :param method: RTM analysis method. Must be one of 'srtm', 'frtm', 'mrtm-original', 'mrtm' or 'mrtm2'. :type method: str :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. .. py:method:: run_analysis(bounds: Union[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. :meth:`validate_analysis_inputs` 2. :meth:`calculate_fit` 3. :meth:`calculate_fit_properties` :param bounds: Optional boundaries for parameters for fitting function. :type bounds: Union[None, np.ndarray], optional :param t_thresh_in_mins: Threshold time in minutes for the MRTM analyses. :type t_thresh_in_mins: float, optional :param k2_prime: Input for the modified RTM (MRTM2, FRTM2, and SRTM2) analyses. :type k2_prime: float, optional :returns: None .. py:method:: 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. :param k2_prime: k2 prime value. :type k2_prime: float :param t_thresh_in_mins: Threshold time for MRTM analyses. :type t_thresh_in_mins: float :raises ValueError: If an input required for the selected method is `None`. .. py:method:: calculate_fit(bounds: Union[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. :meth:`validate_analysis_inputs` 2. :meth:`safe_load_tac` for both reference and ROI TACs 3. Creates a :class:`FitTACWithRTMs` instance and fits TAC to the model :param bounds: Boundaries for parameters for fitting function. :type bounds: Union[None, np.ndarray] :param t_thresh_in_mins: Threshold time for MRTM analyses. :type t_thresh_in_mins: float :param k2_prime: k2 prime value. :type k2_prime: float :param tac_load_kwargs: Additional keyword arguments for the loading TAC function. :type tac_load_kwargs: Any :returns: *FitResults* -- Object containing fit results. .. py:method:: calculate_fit_properties(fit_results: Union[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: :meth:`_calc_frtm_or_srtm_fit_props` is used. 2. For 'mrtm' methods: :meth:`_calc_mrtm_fit_props` is used. :param fit_results: The fit results. :type fit_results: Union[np.ndarray, tuple[np.ndarray, np.ndarray]] :param t_thresh_in_mins: Threshold time for MRTM analyses. :type t_thresh_in_mins: float :param k2_prime: k2 prime value for 'mrtm' based methods. :type k2_prime: float :returns: None .. py:method:: 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. .. py:method:: __call__(bounds, t_thresh_in_mins, k2_prime) .. py:method:: _calc_mrtm_fit_props(fit_results: Union[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 :meth:`calculate_fit_properties`. :param fit_results: Resulting fit parameters. :type fit_results: np.ndarray :param k2_prime: k2 prime value for 'mrtm' based methods. :type k2_prime: float :param t_thresh_in_mins: Threshold time for MRTM analyses. :type t_thresh_in_mins: float .. py:method:: _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 :meth:`calculate_fit_properties`. :param fit_results: Tuple containing the fit parameters and their corresponding fit covariances. :type fit_results: tuple[np.ndarray, np.ndarray] .. py:method:: _get_pretty_srtm_fit_param_vals(param_fits: numpy.ndarray, reduced: bool = False) -> dict :staticmethod: 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``. :param param_fits: array containing the fit parameters. :type param_fits: np.ndarray :returns: *dict* -- Dictionary of fit parameters and their corresponding values. .. py:method:: _get_pretty_frtm_fit_param_vals(param_fits: numpy.ndarray, reduced: bool = False) -> dict :staticmethod: 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``. :param param_fits: array containing the fit parameters. :type param_fits: np.ndarray :returns: *dict* -- Dictionary of fit parameters and their corresponding values.