MultiTACRTMAnalysis ======================================================== .. py:class:: petpal.kinetic_modeling.rtm_analysis.MultiTACRTMAnalysis(ref_tac_path: str, roi_tacs_dir: str, output_directory: str, output_filename_prefix: str, method: str) Bases: :py:obj:`RTMAnalysis`, :py:obj:`petpal.utils.time_activity_curve.MultiTACAnalysisMixin` A class for performing reference tissue model (RTM) analysis on multiple tissue TACs. :ivar ref_tac_path: Path to the reference TAC file. :vartype ref_tac_path: str :ivar roi_tacs_dir: Directory containing region of interest TAC files. :vartype roi_tacs_dir: str :ivar output_directory: Directory for saving analysis results. :vartype output_directory: str :ivar output_filename_prefix: Prefix for output filenames. :vartype output_filename_prefix: str :ivar method: Method used for RTM analysis. :vartype method: str Initializes the MultiTACRTMAnalysis object with required paths and analysis method. :param ref_tac_path: Path to the reference TAC file. :type ref_tac_path: str :param roi_tacs_dir: Directory containing region of interest TAC files. :type roi_tacs_dir: str :param output_directory: Directory for saving analysis results. :type output_directory: str :param output_filename_prefix: Prefix for output filenames. :type output_filename_prefix: str :param method: Method used for RTM analysis. :type method: str .. py:method:: init_analysis_props(method: str) -> list[dict] Initializes analysis properties for each tissue TAC using the specified method. Overrides :meth:`RTMAnalysis.init_analysis_props`. :param method: Method used for initializing analysis properties. :type method: str :returns: *list[dict]* -- A list of analysis property dictionaries for each TAC. .. py:method:: calculate_fit(bounds: Union[None, numpy.ndarray] = None, t_thresh_in_mins: float = None, k2_prime: float = None) -> list Calculates the fit for each TAC, updating the analysis properties with model fit results. Overrides :meth:`RTMAnalysis.calculate_fit`. :param bounds: Bounds for the fitting parameters. Defaults to None. :type bounds: Union[None, np.ndarray], optional :param t_thresh_in_mins: Threshold in minutes for fit calculation. Defaults to None. :type t_thresh_in_mins: float, optional :param k2_prime: A reference tissue model parameter. Defaults to None. :type k2_prime: float, optional :param \*\*tac_load_kwargs: Additional keyword arguments for TAC loading. :returns: *list* -- A list of fit results for each TAC. .. py:method:: calculate_fit_properties(fit_results: list[numpy.ndarray], t_thresh_in_mins: float = None, k2_prime: float = None) Calculates additional properties of the fit based on the fit results and threshold for each TAC. Overrides :meth:`RTMAnalysis.calculate_fit_properties`. :param fit_results: Results from the fitting procedure. :type fit_results: list[np.ndarray] :param t_thresh_in_mins: Threshold in minutes used for fitting. Defaults to None. :type t_thresh_in_mins: float, optional :param k2_prime: A reference tissue model parameter. Defaults to None. :type k2_prime: float, optional .. py:method:: save_analysis(output_as_tsv: bool = True, output_as_json: bool = False) Saves the analysis results to a TSV file as a table with fit parameters for each ROI. :param output_as_tsv: Set True to write results to TSV table. Default True. :type output_as_tsv: bool :param output_as_json: Set True to write results to a folder with one JSON file per region. Default False. :type output_as_json: bool :raises RuntimeError: If 'run_analysis' method has not been called before save_analysis. .. py:method:: __call__(output_as_tsv: bool = True, output_as_json: bool = False, **run_kwargs) Runs :meth:`run_analysis` and :meth:`save_analysis` to run the analysis and save the analysis properties. :param output_as_tsv: Set True to write results to TSV table. Default True. :type output_as_tsv: bool :param output_as_json: Set True to write results to a folder with one JSON file per region. Default False. :type output_as_json: bool :param run_kwargs: Additional keyword arguments used in the analysis. These are passed on to :meth:`run_analysis`. .. 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:: _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. .. py:property:: input_tac_path Gets the input TAC file path. .. py:property:: tacs_dir Gets the TAC directory path. .. py:property:: reference_tac_path Gets the reference TAC file path. .. py:method:: is_valid_tacs_dir(tacs_dir: str) Validates the TAC directory by checking for TAC files. :param tacs_dir: Directory to validate. :type tacs_dir: str :returns: *bool* -- True if valid, otherwise False. .. py:method:: get_tacs_list_from_dir(tacs_dir: str) -> list[str] :staticmethod: Retrieves a sorted list of TAC file paths from a directory. :param tacs_dir: Directory from which to retrieve TAC files. :type tacs_dir: str :returns: *list[str]* -- Sorted list of TAC file paths. .. py:method:: get_tacs_objects_dict_from_files_list(tacs_files_list: list[str]) :staticmethod: Creates a dict of TAC objects from a list of file paths. :param tacs_files_list: List of TAC file paths. :type tacs_files_list: list[str] :returns: *dict* -- Dictionary of region name-TAC object pairs. .. py:method:: get_tacs_objects_dict_from_dir(tacs_dir: str) -> dict :staticmethod: Creates a dict of TAC objects from a directory of TAC files. :param tacs_dir: A directory of TAC files. :type tacs_dir: str :returns: *dict* -- Dictionary of region name-TAC object pairs. .. py:method:: get_tacs_objects_list_from_files_list(tacs_files_list: list[str]) :staticmethod: Creates a list of TAC objects from a list of file paths. :param tacs_files_list: List of TAC file paths. :type tacs_files_list: list[str] :returns: *list[TimeActivityCurve]* -- List of TAC objects. .. py:method:: get_tacs_vals_from_objs_list(tacs_objects_list: list[TimeActivityCurve]) :staticmethod: Extracts TAC values from a list of TAC objects. :param tacs_objects_list: List of TAC objects. :type tacs_objects_list: list[TimeActivityCurve] :returns: *list* -- List of TAC values. .. py:method:: get_tacs_vals_from_dir(tacs_dir: str) Retrieves TAC values from files in a specified directory. :param tacs_dir: Directory containing TAC files. :type tacs_dir: str :returns: *list* -- List of TAC values. .. py:method:: capitalize_first_char_of_str(input_str: str) :staticmethod: Capitalize only the first character of a string, leaving the remainder unchanged. :param input_str: The string to capitalize the first character of. :type input_str: str :returns: *output_str (str)* -- The string with only the first character capitalized. .. py:method:: infer_segmentation_label_from_tac_path(tac_path: str, tac_id: int) :staticmethod: Infers a segmentation label from a TAC file path by analyzing the filename. This method extracts a segment label from the filename of a TAC file. It checks the presence of a `seg-` marker in the filename, which is followed by the segment name. This segment name is then formatted with each part capitalized. If no segment label is found, a default unknown label is generated using the TAC's ID. :param tac_path: Path of the TAC file. :type tac_path: str :param tac_id: ID of the TAC. :type tac_id: int :returns: *str* -- Inferred segmentation label. .. py:method:: infer_segmentation_labels_for_tacs() Infers segmentation labels for TACs. :returns: *list[str]* -- List of inferred segmentation labels. .. seealso:: :meth:`infer_segmentation_label_from_tac_path`