FrameAveragedTACFitter

class petpal.kinetic_modeling.tac_fitting.FrameAveragedTACFitter(input_tac: petpal.utils.time_activity_curve.TimeActivityCurve, roi_tac: petpal.utils.time_activity_curve.TimeActivityCurve, scan_info: petpal.utils.scan_timing.ScanTimingInfo, tcm_model_func: Callable = pet_tcms.model_serial_2tcm_frame_avgd, fit_bounds: None | numpy.ndarray = None, fit_weights: None | numpy.ndarray | str = None, tac_resample_num: int = 8192, **leastsq_kwargs)

A class for fitting Tissue Compartment Models (TCM) to frame-averaged Time Activity Curves (TAC).

This fitter is designed specifically for PET data where TAC values represent frame-averaged measurements rather than instantaneous samples. It uses the lmfit package for robust parameter estimation and handles frame timing information explicitly through ScanTimingInfo.

The class performs high-resolution resampling of input TACs internally, then averages the model predictions over each frame’s duration to match the frame-averaged measurements.

Variables:

• input_tac (TimeActivityCurve) – Input function (plasma) TAC.

• roi_tac (TimeActivityCurve) – Region of interest (tissue) TAC to fit.

• roi_has_err (bool) – Whether the ROI TAC has uncertainty estimates.

• frame_durations (np.ndarray) – Duration of each frame in minutes.

• frame_starts (np.ndarray) – Start time of each frame in minutes.

• frame_ends (np.ndarray) – End time of each frame in minutes.

• model_config (FrameAvgdTcmModelConfig) – Configuration for the TCM model being fitted.

• tcm_func (Callable) – The tissue compartment model function.

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

• initial_guesses (np.ndarray) – Initial parameter guesses.

• bounds_lo (np.ndarray) – Lower parameter bounds.

• bounds_hi (np.ndarray) – Upper parameter bounds.

• tcm_fit_params (lmfit.Parameters) – lmfit Parameters object for fitting.

• tac_resample_num (int) – Number of points for high-resolution TAC resampling.

• fine_roi_tac (TimeActivityCurve) – High-resolution resampled ROI TAC.

• fine_input_tac (TimeActivityCurve) – High-resolution resampled input TAC.

• frame_idx_pairs (np.ndarray) – Index pairs for frame averaging operations.

• weights (np.ndarray or None) – Weights for weighted least squares fitting.

• result_obj (lmfit.minimizer.MinimizerResult or None) – Results from lmfit optimization.

• fit_results (tuple[np.ndarray, np.ndarray] or None) – Fitted parameters and covariance matrix.

• fit_residuals (np.ndarray or None) – Residuals from the fit.

• fit_sum_of_square_residuals (float or None) – Sum of squared residuals.

• fit_tac (TimeActivityCurve or None) – Model-predicted TAC using fitted parameters.

Example

from petpal.utils.time_activity_curve import TimeActivityCurve
from petpal.utils.scan_timing import ScanTimingInfo
import petpal.kinetic_modeling.tcms_as_convolutions as pet_tcm
import petpal.kinetic_modeling.tac_fitting as pet_fit

# Load TACs and scan timing
input_tac = TimeActivityCurve.from_tsv('input.tsv')
roi_tac = TimeActivityCurve.from_tsv('roi.tsv')
scan_info = ScanTimingInfo.from_nifti('pet_image.nii')

# Initialize and run fitter
fitter = pet_fit.FrameAveragedTACFitter(
    input_tac=input_tac,
    roi_tac=roi_tac,
    scan_info=scan_info,
    tcm_model_func=pet_tcm.model_serial_2tcm_frame_avgd
)
fitter.run_fit()

# Access results
fit_params = fitter.fit_results[0]
fit_tac = fitter.fit_tac

See also

• TACFitter for non-frame-averaged fitting

• FrameAveragedTCMAnalysis for complete analysis workflow

• TimeActivityCurve

• ScanTimingInfo

Initialize FrameAveragedTACFitter with TACs, scan timing, and fitting parameters.

Parameters:

• input_tac (TimeActivityCurve) – Input function (plasma) TAC.

• roi_tac (TimeActivityCurve) – Region of interest (tissue) TAC to fit.

• scan_info (ScanTimingInfo) – Scan timing information including frame starts and durations.

• tcm_model_func (Callable, optional) – The frame-averaged TCM function to use for fitting. Defaults to model_serial_2tcm_frame_avgd.

• fit_bounds (np.ndarray or None, optional) – Parameter bounds with shape (num_params, 3). If None, default bounds are used. Defaults to None.

• fit_weights (np.ndarray, str, or None, optional) – Weights for fitting. Can be: None: No weighting (uniform weights); ‘roi’ or ‘roi-tac’ or ‘tac-err’ or ‘stderr’: Use ROI TAC uncertainties; np.ndarray: Custom weight array Defaults to None.

• tac_resample_num (int, optional) – Number of points for high-resolution resampling. Defaults to 8192.

• **leastsq_kwargs – Additional keyword arguments passed to lmfit.Minimizer.leastsq().

Raises:

• AssertionError – If input_tac or roi_tac are not TimeActivityCurve objects, or if scan_info is not a ScanTimingInfo object.

• ValueError – If tcm_model_func is not in the supported models list.

_validate_inputs(input_tac: petpal.utils.time_activity_curve.TimeActivityCurve, roi_tac: petpal.utils.time_activity_curve.TimeActivityCurve, scan_info: petpal.utils.scan_timing.ScanTimingInfo, tcm_model_func: Callable)

Validate input parameters for the fitter.

Parameters:

• input_tac (TimeActivityCurve) – Input function TAC to validate.

• roi_tac (TimeActivityCurve) – ROI TAC to validate.

• scan_info (ScanTimingInfo) – Scan timing information to validate.

• tcm_model_func (Callable) – TCM function to validate.

Raises:

• AssertionError – If TACs are not TimeActivityCurve objects or scan_info is not ScanTimingInfo.

• ValueError – If tcm_model_func is not supported.

_setup_bounds(fit_bounds: numpy.ndarray | None) → numpy.ndarray

Set up parameter bounds for curve fitting.

If bounds are provided, validates their shape. Otherwise, uses default bounds from the model configuration.

Parameters:

fit_bounds (np.ndarray or None) – User-provided bounds with shape (num_params, 3) where each row contains [initial_guess, lower_bound, upper_bound]. If None, default bounds are used.

Returns:

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

Raises:

ValueError – If fit_bounds has incorrect shape for the model.

gen_fit_params()

Generate lmfit Parameters object from bounds.

Creates an lmfit.Parameters object with parameter names, initial values, and bounds configured from the model configuration and bounds arrays.

Returns:

lmfit.Parameters – Configured parameters object for fitting.

See also

• lmfit.create_params()

_setup_weights(fit_weights: numpy.ndarray | str | None) → numpy.ndarray | None

Set up weights for weighted least squares fitting.

Parameters:

fit_weights (np.ndarray, str, or None) –

Specification for weights. Can be: None: No weighting; ‘roi’, ‘roi-tac’, ‘tac-err’, ‘stderr’: Use ROI TAC uncertainties;

np.ndarray: Custom weight array

Returns:

np.ndarray or None – Weight array for fitting, or None for uniform weighting.

Side Effects:

Issues a warning if a string weight specification is not recognized.

run_fit() → None

Run the optimization/fitting process on the frame-averaged data.

Performs the least-squares fitting using lmfit, extracts the fitted parameters and covariance matrix, calculates residuals, and generates the fitted TAC.

Returns:

None

Side Effects:

• result_obj (lmfit.minimizer.MinimizerResult): Stores the complete lmfit result object.

• fit_results (tuple[np.ndarray, np.ndarray]): Stores fitted parameters and covariance matrix.

• fit_residuals (np.ndarray): Stores the residuals from the fit.

• fit_sum_of_square_residuals (float): Stores the sum of squared residuals.

• fit_tac (TimeActivityCurve): Stores the model-predicted TAC using fitted parameters.

See also

• lmfit.Minimizer.leastsq()

__call__()

Execute the fit by calling the instance.

Convenience method that runs run_fit().

Side Effects:

Runs the fitting process and populates result attributes.