MultiTACTCMAnalysis ======================================================= .. py:class:: petpal.kinetic_modeling.tac_fitting.MultiTACTCMAnalysis(input_tac_path: str, roi_tacs_dir: str, output_directory: str, output_filename_prefix: str, compartment_model: str, parameter_bounds: Union[None, numpy.ndarray] = None, weights: Union[float, None, numpy.ndarray] = None, resample_num: int = 512, aif_fit_thresh_in_mins: float = 40.0, max_func_iters: int = 2500, ignore_blood_volume: bool = False) Bases: :py:obj:`TCMAnalysis`, :py:obj:`petpal.utils.time_activity_curve.MultiTACAnalysisMixin` A class for performing tissue compartment model (TCM) analysis on multiple tissue TACs. :ivar input_tac_path: Path to the input TAC file. :vartype input_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 compartment_model: Name of the compartment model to use. :vartype compartment_model: str :ivar parameter_bounds: Bounds for the fitting parameters. Defaults to None. :vartype parameter_bounds: Union[None, np.ndarray], optional :ivar weights: Weights for fitting. Defaults to None. :vartype weights: Union[float, None, np.ndarray], optional :ivar resample_num: Number of resampling points. Defaults to 512. :vartype resample_num: int :ivar aif_fit_thresh_in_mins: Threshold in minutes for AIF fitting. Defaults to 40.0. :vartype aif_fit_thresh_in_mins: float :ivar max_func_iters: Maximum number of iterations for the fitting function. Defaults to 2500. :vartype max_func_iters: int :ivar ignore_blood_volume: Whether to ignore blood volume in the analysis. Defaults to False. :vartype ignore_blood_volume: bool Initializes the MultiTACTCMAnalysis object with required paths, model parameters, and fitting options. :param input_tac_path: Path to the input TAC file. :type input_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 compartment_model: Name of the compartment model to use. :type compartment_model: str :param parameter_bounds: Bounds for the fitting parameters. Defaults to None. :type parameter_bounds: Union[None, np.ndarray], optional :param weights: Weights for fitting. Defaults to None. :type weights: Union[float, None, np.ndarray], optional :param resample_num: Number of resampling points. Defaults to 512. :type resample_num: int, optional :param aif_fit_thresh_in_mins: Threshold in minutes for AIF fitting. Defaults to 40.0. :type aif_fit_thresh_in_mins: float, optional :param max_func_iters: Maximum number of iterations for the fitting function. Defaults to 2500. :type max_func_iters: int, optional :param ignore_blood_volume: Whether to ignore blood volume in the analysis. Defaults to False. :type ignore_blood_volume: bool, optional .. py:method:: init_analysis_props() Initializes analysis properties for each tissue TAC. Overrides :meth:`TCMAnalysis.init_analysis_props`. :returns: *list[dict]* -- A list of analysis property dictionaries for each TAC. .. py:method:: calculate_fit() Calculates the fit for each TAC, updating the analysis properties with model fit results. Overrides :meth:`TCMAnalysis.calculate_fit`. .. py:method:: calculate_fit_properties() Updates analysis properties with formatted fit values for each TAC. Overrides :meth:`TCMAnalysis.calculate_fit_properties`. .. py:method:: save_analysis() Saves the analysis results to a JSON file for each TAC. Overrides :meth:`TCMAnalysis.save_analysis`. :raises RuntimeError: If 'run_analysis' method has not been run before 'save_analysis'. .. py:method:: validated_tcm(compartment_model: str) -> str :staticmethod: Validates the type of tissue compartment model. Runs :meth:`~.ConvTcmModel.resolve_model_name` for validation, and returns the normalized string by running :meth:`~.ConvTcmModel.normalize_name`. :param compartment_model: The name of the compartment model. :type compartment_model: str :returns: *str* -- The transformed name of the validated compartment model if it was valid. :raises KeyError: If the provided compartment model is not one of '1tcm', '2tcm-k4zero', 'serial-2tcm' or '2tcm'. .. py:method:: _get_tcm_function(compartment_model: str) -> Callable :staticmethod: Returns the corresponding function for the provided tissue compartment model used for the fitting class. Runs :meth:`~.ConvTcmModel.resolve_model_name` for validation, and returns the appropriate function. :param compartment_model: The name of the tissue compartment model. :returns: *function* -- The corresponding function for the tissue compartment model. :raises KeyError: If the provided tissue compartment model name does not correspond to any known models. .. seealso:: * :func:`gen_tac_1tcm_cpet_from_tac` * :func:`gen_tac_2tcm_with_k4zero_cpet_from_tac` * :func:`gen_tac_2tcm_cpet_from_tac` * :class:`~.TACFitter` .. py:method:: run_analysis() Runs the fitting analysis given the file-paths and method. :meth:`calculate_fit` and :meth:`calculate_fit_properties` are run, and the analysis-has-been-fun flag is set to true. This method first calculates the fit, then updates the analysis properties with the fit results and finally sets the flag denoting that analysis has been successfully run. .. py:method:: update_props_with_formatted_fit_values(fit_results, fit_props_dict: dict) Update the analysis properties dictionary with formatted fit results. Extracts fit parameters and standard errors from fit results, formats them using pretty parameter names, and updates the provided properties dictionary. :param fit_results: Tuple containing (fit_params, fit_covariances) from the fitting process. :type fit_results: tuple :param fit_props_dict: Dictionary to update with formatted fit values and errors. :type fit_props_dict: dict Side Effects: Updates the FitProperties section of fit_props_dict with formatted FitValues, FitStdErr, and Bounds. .. py:method:: _generate_pretty_params(results: numpy.ndarray) -> dict Transforms array of results into a formatted dictionary. This method formats the fitting results into a more human-readable form. If the fitting was done without blood volume, it formats all values as 'k_i': value. Otherwise it formats all but the last as 'k_i': value and the last as 'vb': value. :param results: The array of fitting results. :type results: np.ndarray :returns: *dict* -- The formatted fitting results as {param: value} pairs. In the case of TACFitterWithBloodVolume, the last parameter will be named 'vb', others 'k_i'. In the case of TACFitterWithoutBloodVolume, parameters will be named 'k_i'. .. py:method:: _generate_pretty_bounds(bounds: Union[numpy.ndarray, None]) -> dict Transforms array of bounds into a formatted dictionary. This method creates a dictionary of the fitting parameters and their corresponding initial values and lower and upper bounds. The keys of the dictionary are the names of the fitting parameters from :meth:`_generate_pretty_params` method. :param bounds: The array of parameter bounds. :type bounds: np.ndarray :returns: *dict* -- The fitting parameters with their corresponding initial values, and lower and upper bounds, in the following format: {param: {'initial': val, 'lo': lo, 'hi': hi}} .. py:method:: __call__() .. 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`