PCAGuidedIdifFitterBase#

class petpal.input_function.pca_guided_idif.PCAGuidedIdifFitterBase(input_image_path: str, mask_image_path: str, output_tac_path: str, num_pca_components: int, pca_comp_filter_min_value: float, pca_comp_threshold: float, verbose: bool)#

Bases: PCAGuidedIdifBase

Base class for calculating the PCA-guided IDIF by fitting to find the best voxels

This class extends PCAGuidedIdifBase and provides a framework for applying optimizations and heuristics (e.g., voxel count, peak sharpness, and smoothness) to filter and refine the targeted voxel selection for IDIF estimation.

Notes

This class provides a foundation for subclasses to customize voxel filtering and optimization strategies by overriding the static methods for term functions.

See PCAGuidedIdifFitter for a concrete implementation example.

Initializes the PCA-guided IDIF fitter base-class.

Parameters:

  • input_image_path (str) – Path to the dynamic input image.

  • mask_image_path (str) – Path to the mask image used to select the region of interest.

  • output_tac_path (str) – Path where the output TAC data will be saved.

  • num_pca_components (int) – Number of PCA components to compute.

  • pca_comp_filter_min_value (float) – Minimum value for filtering PCA components.

  • pca_comp_threshold (float) – Threshold for filtering PCA components.

  • verbose (bool) – Whether to enable detailed diagnostic output.

Side Effects:

  • Initializes several fitting-related attributes (e.g., alpha, beta, _fitting_params).

  • Calculates PCA filtering flags and signs based on the passed thresholds.

property pca_comp_filter_flag_threshold: float#
property pca_comp_filter_min_val: float#
static get_pca_component_filter_flags(pca_components: numpy.ndarray, comp_min_val: float = 0.0, threshold: float = 0.1) → numpy.ndarray[bool]#

Generates filtering flags for PCA components based on their contribution.

Given the comp_min_val, we check how many of the time-points of the PCA components are above the threshold, then threshold determines if the component contributes with > (if the fraction of higher points is above the threshold) or < (if the fraction of higher points is below the threshold).

Parameters:

  • pca_components (np.ndarray) – Array of PCA components for evaluation.

  • comp_min_val (float) – Minimum value for PCA components to contribute positively.

  • threshold (float) – Threshold for rejecting components with insufficient contributions.

Returns:

np.ndarray[bool] – Boolean flags indicating whether a PCA filters less than, or greater than.

static get_pca_filter_signs_from_flags(pca_component_filter_flags: numpy.ndarray[bool]) → list[str]#

Derives signs (‘>’ or ‘<’) for PCA components based on their filtering flags.

See also

get_pca_component_filter_flags()

Parameters:

pca_component_filter_flags (np.ndarray[bool]) – Filtering flags for PCA components.

Returns:

list[str] – List of signs corresponding to the filter flags.

static _voxel_term_func(voxel_nums: float) → float#
Abstractmethod:

Abstract method for computing the voxel-number term for the optimization function.

Parameters:

voxel_nums (float) – Number of valid voxels contributing to the TACs.

Returns:

float – Calculated voxel term.

static _noise_term_func(tac_stderrs: numpy.ndarray[float]) → float#
Abstractmethod:

Abstract method for computing the noise term for the optimization function.

Parameters:

tac_stderrs (np.ndarray[float]) – Standard deviations of TACs from voxel data.

Returns:

float – Calculated noise term.

static _smoothness_term_func(tac_values: numpy.ndarray[float]) → float#
Abstractmethod:

Abstract method for computing the smoothness term for the optimization function.

Parameters:

tac_values (np.ndarray[float]) – Mean values of TACs from voxel data.

Returns:

float – Calculated smoothness term.

static _peak_term_func(tac_peak_ratio: float) → float#
Abstractmethod:

Abstract method for computing the peak term for the optimization function.

Parameters:

tac_peak_ratio (float) – Ratio of the voxel TAC peak to the peak of the mask average

Returns:

float – Calculated peak term.

static _generate_quantile_params(num_components: int = 3, value: float = 0.5, lower: float = 0.0001, upper: float = 0.999) → lmfit.Parameters#

Generates initial fitting quantile parameters for determining voxel filters.

Parameters:

  • num_components (int) – The number of PCA components to generate parameters for.

  • value (float) – Default value for each quantile parameter (e.g., median = 0.5).

  • lower (float) – Lower bound for the quantile parameter (default is 1e-4).

  • upper (float) – Upper bound for the quantile parameter (default is 0.999).

Returns:

lmfit.Parameters – A parameter set with quantile values for each PCA component.

static calculate_voxel_mask_from_quantiles(params: lmfit.Parameters, pca_values_per_voxel: numpy.ndarray, quantile_flags: numpy.ndarray[bool]) → numpy.ndarray[bool]#

Calculates a mask to identify selected voxels based on quantile thresholds.

Given the passed in quantile params, we check if the value of the principal component for a voxel is above the quantile threshold, then quantile_flags is used to flip the signs of the components which should be lower than. For each voxel, the boolean product is calculated to determine if the voxel should be a part of the mask or not. Only voxels where every PC is above (or below) the quantile thresholds in params are included in the mask.

Parameters:

  • params (lmfit.Parameters) – Quantile parameters for each PCA component.

  • pca_values_per_voxel (np.ndarray) – PCA values for every voxel.

  • quantile_flags (np.ndarray[bool]) – Filtering flags for quantile-based masking.

Returns:

np.ndarray[bool] – Mask identifying selected voxels passing the quantile criteria.

calculate_filter_flags_and_signs(comp_min_val: float, threshold: float)#

Updates PCA filter flags and their respective signs based on component values.

Parameters:

  • comp_min_val (float) – Minimum acceptable value for filtering PCA components.

  • threshold (float) – Threshold percentage for filtering components.

Side Effects:

  • Updates the pca_filter_flags attribute with new flags for indicating filtered components.

  • Updates the filter_signs attribute with the corresponding value comparison signs based on the flags.

residual(params: lmfit.Parameters, pca_values_per_voxel: numpy.ndarray[float], quantile_flags: numpy.ndarray[bool], voxel_tacs: numpy.ndarray, alpha: float, beta: float) → float#

Calculates the residual (objective function) for optimization.

The residual has the following terms:

\[\mathcal{L} = \mathrm{VoxelTerm} + \mathrm{NoiseTerm} + (\alpha\cdot\mathrm{PeakTerm}) + (\beta\cdot\mathrm{SmoothnessTerm})\]
Parameters:

  • params (lmfit.Parameters) – Parameters for the optimization.

  • pca_values_per_voxel (np.ndarray[float]) – PCA values for each voxel.

  • quantile_flags (np.ndarray[bool]) – Flags indicating quantile filtering.

  • voxel_tacs (np.ndarray) – TACs for valid voxels.

  • alpha (float) – Weight for the peak term.

  • beta (float) – Weight for the smoothness term.

Returns:

float – Residual value.

run(alpha: float, beta: float, method: str = 'ampgo', **method_kwargs)#

Runs the PCA-guided IDIF fitting process using optimization.

Parameters:

  • alpha (float) – Weight for the peak term in the optimization.

  • beta (float) – Weight for the smoothness term in the optimization.

  • method (str) – Optimization method to use (default is ‘ampgo’).

  • **method_kwargs – Additional keyword arguments for the optimizer.

Side Effects:

  • Updates optimization-related attributes (e.g., fit_result, fit_quantiles).

  • Updates selected_voxels_mask with the best voxel subset.

  • Marks analysis_has_run as True.

Notes

The run method uses the residual function as the target for minimization.

__call__(alpha: float, beta: float, method: str, **meth_kwargs) → None#

Callable interface for running the fitting process and saving results.

Parameters:

  • alpha (float) – Weight for the peak term in the optimization.

  • beta (float) – Weight for the smoothness term in the optimization.

  • method (str) – Optimization method to use.

  • **method_kwargs – Additional keyword arguments for the optimizer.

Side Effects:

  • Executes the analysis and saves the resulting TAC data to the output file.

perform_temporal_pca()#

Performs PCA decomposition on the dynamic image data within the specified mask.

This method applies temporal PCA analysis on the input dynamic image constrained to the region defined by the mask. The resulting PCA object and fitted data are stored as attributes for subsequent processing. Uses extract_roi_voxel_tacs_from_image_using_mask()

Attributes Updated:

  • pca_obj

  • pca_fit

Raises:

ValueError – If PCA analysis fails during execution.

rescale_tacs(rescale_constant: float = CONVERT_kBq_to_mCi_) → None#

Rescales the time-activity curves (TACs) and associated data by a constant factor.

This method uniformly rescales voxel-level TACs, IDIF values, PCA outputs, and other TAC-associated metrics using the specified constant. The default value corresponds to a pre-defined scaling factor to convert units between kilobecquerels and millicuries.

Parameters:

rescale_constant (float) – The constant factor used for rescaling. Must be greater than zero. Default is 37000.0.

Attributes Updated:

  • mask_voxel_tacs

  • mask_avg

  • mask_std

  • mask_peak_val

  • idif_vals

  • idif_errs

  • prj_idif_vals

  • prj_idif_errs

  • selected_voxels_tacs

  • selected_voxels_prj_tacs

Raises:

AssertionError – If the rescale_constant is not greater than 0.

save()#

Saves the computed IDIF and related metrics to a file.

This method exports the time-activity curves (TACs) and other analysis results into a tab-delimited text file. The file will include time points, IDIF values, errors, PCA-projected metrics, and mask-derived averages, along with their associated standard deviations.

The output file is saved at the path specified in the output_tac_path attribute.

Raises:

AssertionError – If the analysis has not been run prior to calling this method.

Output Format:
The saved text file will have the following tab-delimited columns:

  • time: Time in minutes.

  • idif: IDIF values.

  • d_idif: Errors (standard deviations) for IDIF.

  • prj_idif: PCA-projected IDIF values.

  • d_prj_idif: Errors (standard deviations) for PCA-projected IDIF values.

  • mask: Mean voxel activity in the mask.

  • d_mask: Standard deviation of voxel activity in the mask.

calculate_tacs_from_mask() → None#

Calculates Time-Activity Curves (TACs) and IDIF-related metrics from the selected voxel mask.

This method processes the data from selected voxels within a previously defined mask and computes key metrics such as mean IDIF values, standard deviations, PCA-projected values, and their respective errors. It utilizes PCA transformations to refine the IDIF and ensure consistency with the voxel data.

Side Effects:

idif_vals (np.ndarray): Mean IDIF values calculated from the selected voxel TACs. idif_errs (np.ndarray): Standard deviations of the IDIF values derived from selected voxels. prj_idif_vals (np.ndarray): Mean PCA-projected IDIF values, with negative values set to zero. prj_idif_errs (np.ndarray): Standard deviations for the PCA-projected IDIF values.

Raises:

AssertionError – If the analysis has not been previously performed (i.e., .run() was not called).

Notes

  • Negative PCA-projected IDIF values are set to zero since negative values are non-physical.

property idif_tac#

Get the calculated IDIF TAC

Returns:

TimeActivityCurve – TAC object with (times, idif_vals)

See also

TimeActivityCurve

property idif_tac_werr#

Get the calculated IDIF TAC with the standard deviations

Returns:

TimeActivityCurve – TAC object with (times, idif_vals, idif_stderrs)

See also

TimeActivityCurve

property prj_idif_tac#

Get the calculated PCA-projected IDIF TAC

Returns:

TimeActivityCurve – TAC object with (times, projected_idif_vals)

See also

TimeActivityCurve

property prj_idif_tac_werr#

Get the calculated PCA-projected IDIF TAC with the standard deviations

Returns:

TimeActivityCurve – TAC object with (times, projected_idif_vals, projected_idif_stderrs)

See also

TimeActivityCurve