FrameAveragedTCMAnalysis ============================================================ .. py:class:: petpal.kinetic_modeling.tac_fitting.FrameAveragedTCMAnalysis(input_tac_path: str, roi_tac_path: str, scan_info_path: str, output_directory: str, output_filename_prefix: str, compartment_model: str, parameter_bounds: None | numpy.ndarray = None, weights: float | None | numpy.ndarray = None, resample_num: int = 8192) A class for complete TCM analysis using files on frame-averaged TAC data. This class provides a high-level interface for performing tissue compartment model fitting on frame-averaged PET data. It handles file I/O, fitting, and result export including JSON parameter files. It wraps :class:`FrameAveragedTACFitter` with additional functionality for loading data from files and saving results. :ivar input_tac_path: Absolute path to input TAC file. :vartype input_tac_path: str :ivar roi_tac_path: Absolute path to ROI TAC file. :vartype roi_tac_path: str :ivar scan_info_path: Absolute path to scan timing information. Typically a JSON file with metadata from a NIfTI file. Can also be the path to a NIfTI file if the metadata have the same name as the NIfTI file, but the extension is json. :vartype scan_info_path: str :ivar output_directory: Absolute path to output directory for results. :vartype output_directory: str :ivar output_filename_prefix: Prefix for output filenames. :vartype output_filename_prefix: str :ivar compartment_model: Normalized name of the compartment model. :vartype compartment_model: str :ivar short_tcm_name: Shortened model name without hyphens. :vartype short_tcm_name: str :ivar _tcm_func: The TCM function corresponding to the compartment model. :vartype _tcm_func: Callable :ivar _model_config: Configuration for the TCM model. :vartype _model_config: FrameAvgdTcmModelConfig :ivar bounds: Parameter bounds for fitting. :vartype bounds: np.ndarray or None :ivar weights: Weights for fitting. :vartype weights: float, np.ndarray, or None :ivar resample_num: Number of points for TAC resampling. :vartype resample_num: int :ivar fitter_class: The fitter class to use (FrameAveragedTACFitter). :vartype fitter_class: type :ivar analysis_props: Dictionary containing analysis properties and results. :vartype analysis_props: dict :ivar fit_results: Fitted parameters and covariance matrix. :vartype fit_results: tuple or None :ivar _has_analysis_been_run: Flag indicating if analysis has been executed. :vartype _has_analysis_been_run: bool .. rubric:: Example .. code-block:: python import petpal.kinetic_modeling.tac_fitting as pet_fit analysis = pet_fit.FrameAveragedTCMAnalysis( input_tac_path='./input.tsv', roi_tac_path='./roi.tsv', scan_info_path='./pet_image.nii.gz', # Assumes that ./pet_image.json is the metadata file output_directory='./results', output_filename_prefix='subject01', compartment_model='serial-2tcm' ) # Run and save analysis() # Or step by step analysis.run_analysis() analysis.save_analysis() .. seealso:: * :class:`FrameAveragedTACFitter` * :class:`FrameAveragedMultiTACTCMAnalysis` for multiple ROIs * :class:`TCMAnalysis` for non-frame-averaged analysis Initialize a FrameAveragedTCMAnalysis instance. :param input_tac_path: Path to the input/plasma TAC file. :type input_tac_path: str :param roi_tac_path: Path to the ROI/tissue TAC file. :type roi_tac_path: str :param scan_info_path: Path to scan timing information file. Typically a JSON file with metadata from a NIfTI file. Can also be the path to a NIfTI file if the metadata have the same name as the NIfTI file, but the extension is json. :type scan_info_path: 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 (e.g., '1tcm', 'serial-2tcm'). :type compartment_model: str :param parameter_bounds: Parameter bounds with shape (num_params, 3). Defaults to None. :type parameter_bounds: np.ndarray or None, optional :param weights: Weights for fitting. Defaults to None. :type weights: float, np.ndarray, or None, optional :param resample_num: Number of points for TAC resampling. Defaults to 8192. :type resample_num: int, optional .. py:method:: init_analysis_props() -> dict Initialize the analysis properties dictionary structure. Creates a dictionary to store metadata, file paths, model information, and fit results. This dictionary can be saved as a JSON file for parsing results. :returns: *dict* -- Initialized dictionary with analysis properties structure including: - FilePathPTAC: Path to input TAC - FilePathTTAC: Path to ROI TAC - TissueCompartmentModel: Model name - FitProperties: Nested dict with FitValues, FitStdErr, Bounds, and ResampleNum .. seealso:: * :meth:`calculate_fit_properties` .. py:method:: validated_tcm_name(compartment_model: str) -> str :staticmethod: Validate and normalize a tissue compartment model name. :param compartment_model: The compartment model name to validate. :type compartment_model: str :returns: *str* -- The normalized model name. :raises ValueError: If the model name is not valid for frame-averaged models. .. seealso:: * :meth:`~.FrameAvgdTcmModelConfig.normalize_name` .. py:method:: validated_tcm_function(compartment_model: str) -> Callable :staticmethod: Get the TCM function corresponding to a model name. :param compartment_model: The compartment model name. :type compartment_model: str :returns: *Callable* -- The frame-averaged TCM function. :raises ValueError: If the model name does not correspond to a known frame-averaged model. .. seealso:: * :meth:`FrameAvgdTcmModelConfig.resolve_model_name` .. py:method:: __call__(pretty_params: bool = False) Execute the complete analysis workflow. Convenience method that runs the analysis and saves results. :param pretty_params: If True, use LaTeX-formatted parameter names in output. Defaults to False. :type pretty_params: bool, optional Side Effects: Runs the fit analysis and saves results to the output directory. .. seealso:: * :meth:`run_analysis` * :meth:`save_analysis` .. py:method:: run_analysis(pretty_params: bool = False) Run the fitting analysis workflow. Executes :meth:`calculate_fit` and :meth:`calculate_fit_properties`, then sets the analysis-has-been-run flag. :param pretty_params: If True, use LaTeX-formatted parameter names. Defaults to False. :type pretty_params: bool, optional Side Effects: - Populates fit_results with fitted parameters and covariances. - Updates analysis_props with formatted fit values. - Sets _has_analysis_been_run to True. .. py:method:: save_analysis() Save analysis results to a JSON file. Saves the analysis_props dictionary containing fit results and metadata to a JSON file in the output directory. The filename is constructed from the output prefix, model name, and '_fitprops.json' suffix. :raises RuntimeError: If :meth:`run_analysis` has not been called before this method. Side Effects: Writes a JSON file to the output directory. .. py:method:: calculate_fit() Perform the TCM fit on the loaded TAC data. Loads TACs and scan timing from files, creates a :class:`FrameAveragedTACFitter` instance, runs the fit, and stores results. Side Effects: - Populates fit_results with fitted parameters and covariance matrix. - Sets bounds if they were None initially. .. seealso:: * :class:`~.FrameAveragedTACFitter` * :class:`~.TimeActivityCurve` * :class:`~.ScanTimingInfo` .. py:method:: calculate_fit_properties(pretty_params: bool = False) Calculate and format fit properties for output. Extracts fitted parameters, standard errors, and bounds, then formats them into the analysis_props dictionary. :param pretty_params: If True, use LaTeX-formatted parameter names. Defaults to False. :type pretty_params: bool, optional Side Effects: Updates the analysis_props dictionary with formatted fit results. .. seealso:: * :meth:`update_props_with_formatted_fit_values` .. py:method:: update_props_with_formatted_fit_values(fit_values: numpy.ndarray, fit_covars: numpy.ndarray, param_bounds: numpy.ndarray, fit_props_dict: dict, pretty_params: bool = False) -> None Update properties dictionary with formatted fit results. Computes standard errors from covariances, formats parameter names (optionally with LaTeX), and updates the fit properties dictionary. :param fit_values: Array of fitted parameter values. :type fit_values: np.ndarray :param fit_covars: Covariance matrix from the fit. :type fit_covars: np.ndarray :param param_bounds: Parameter bounds array. :type param_bounds: np.ndarray :param fit_props_dict: Dictionary to update with formatted results. :type fit_props_dict: dict :param pretty_params: If True, use LaTeX-formatted parameter names. Defaults to False. :type pretty_params: bool, optional Side Effects: Updates the FitProperties section of fit_props_dict with FitValues, FitStdErr, and Bounds. .. py:method:: _generate_formatted_bounds(param_bounds: numpy.ndarray, pretty_params: bool = False) -> dict Format parameter bounds into a dictionary structure. :param param_bounds: Parameter bounds array with shape (num_params, 3). :type param_bounds: np.ndarray :param pretty_params: If True, use LaTeX-formatted parameter names. Defaults to False. :type pretty_params: bool, optional :returns: *dict* -- Formatted bounds dictionary with structure: {param_name: {'initial': val, 'lo': lo_bound, 'hi': hi_bound}}