FrameAveragedTCMAnalysis

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 FrameAveragedTACFitter with additional functionality for loading data from files and saving results.

Variables:

• input_tac_path (str) – Absolute path to input TAC file.

• roi_tac_path (str) – Absolute path to ROI TAC file.

• scan_info_path (str) – 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.

• output_directory (str) – Absolute path to output directory for results.

• output_filename_prefix (str) – Prefix for output filenames.

• compartment_model (str) – Normalized name of the compartment model.

• short_tcm_name (str) – Shortened model name without hyphens.

• _tcm_func (Callable) – The TCM function corresponding to the compartment model.

• _model_config (FrameAvgdTcmModelConfig) – Configuration for the TCM model.

• bounds (np.ndarray or None) – Parameter bounds for fitting.

• weights (float, np.ndarray, or None) – Weights for fitting.

• resample_num (int) – Number of points for TAC resampling.

• fitter_class (type) – The fitter class to use (FrameAveragedTACFitter).

• analysis_props (dict) – Dictionary containing analysis properties and results.

• fit_results (tuple or None) – Fitted parameters and covariance matrix.

• _has_analysis_been_run (bool) – Flag indicating if analysis has been executed.

Example

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()

See also

• FrameAveragedTACFitter

• FrameAveragedMultiTACTCMAnalysis for multiple ROIs

• TCMAnalysis for non-frame-averaged analysis

Initialize a FrameAveragedTCMAnalysis instance.

Parameters:

• input_tac_path (str) – Path to the input/plasma TAC file.

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

• scan_info_path (str) – 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.

• output_directory (str) – Directory for saving analysis results.

• output_filename_prefix (str) – Prefix for output filenames.

• compartment_model (str) – Name of the compartment model (e.g., ‘1tcm’, ‘serial-2tcm’).

• parameter_bounds (np.ndarray or None, optional) – Parameter bounds with shape (num_params, 3). Defaults to None.

• weights (float, np.ndarray, or None, optional) – Weights for fitting. Defaults to None.

• resample_num (int, optional) – Number of points for TAC resampling. Defaults to 8192.

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

See also

• calculate_fit_properties()

static validated_tcm_name(compartment_model: str) → str

Validate and normalize a tissue compartment model name.

Parameters:

compartment_model (str) – The compartment model name to validate.

Returns:

str – The normalized model name.

Raises:

ValueError – If the model name is not valid for frame-averaged models.

See also

• normalize_name()

static validated_tcm_function(compartment_model: str) → Callable

Get the TCM function corresponding to a model name.

Parameters:

compartment_model (str) – The compartment model name.

Returns:

Callable – The frame-averaged TCM function.

Raises:

ValueError – If the model name does not correspond to a known frame-averaged model.

See also

• FrameAvgdTcmModelConfig.resolve_model_name()

__call__(pretty_params: bool = False)

Execute the complete analysis workflow.

Convenience method that runs the analysis and saves results.

Parameters:

pretty_params (bool, optional) – If True, use LaTeX-formatted parameter names in output. Defaults to False.

Side Effects:

Runs the fit analysis and saves results to the output directory.

See also

• run_analysis()

• save_analysis()

run_analysis(pretty_params: bool = False)

Run the fitting analysis workflow.

Executes calculate_fit() and calculate_fit_properties(), then sets the analysis-has-been-run flag.

Parameters:

pretty_params (bool, optional) – If True, use LaTeX-formatted parameter names. Defaults to False.

Side Effects:

• Populates fit_results with fitted parameters and covariances.

• Updates analysis_props with formatted fit values.

• Sets _has_analysis_been_run to True.

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 run_analysis() has not been called before this method.

Side Effects:

Writes a JSON file to the output directory.

calculate_fit()

Perform the TCM fit on the loaded TAC data.

Loads TACs and scan timing from files, creates a 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.

See also

• FrameAveragedTACFitter

• TimeActivityCurve

• ScanTimingInfo

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.

Parameters:

pretty_params (bool, optional) – If True, use LaTeX-formatted parameter names. Defaults to False.

Side Effects:

Updates the analysis_props dictionary with formatted fit results.

See also

• update_props_with_formatted_fit_values()

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.

Parameters:

• fit_values (np.ndarray) – Array of fitted parameter values.

• fit_covars (np.ndarray) – Covariance matrix from the fit.

• param_bounds (np.ndarray) – Parameter bounds array.

• fit_props_dict (dict) – Dictionary to update with formatted results.

• pretty_params (bool, optional) – If True, use LaTeX-formatted parameter names. Defaults to False.

Side Effects:

Updates the FitProperties section of fit_props_dict with FitValues, FitStdErr, and Bounds.

_generate_formatted_bounds(param_bounds: numpy.ndarray, pretty_params: bool = False) → dict

Format parameter bounds into a dictionary structure.

Parameters:

• param_bounds (np.ndarray) – Parameter bounds array with shape (num_params, 3).

• pretty_params (bool, optional) – If True, use LaTeX-formatted parameter names. Defaults to False.

Returns:

dict –

Formatted bounds dictionary with structure:

{param_name: {‘initial’: val, ‘lo’: lo_bound, ‘hi’: hi_bound}}