PCAGuidedIdifBase#

class petpal.input_function.pca_guided_idif.PCAGuidedIdifBase(input_image_path: str, mask_image_path: str, output_tac_path: str, num_pca_components: int, verbose: bool)#

Bases: object

A base class for PCA-guided Image-Derived Input Function (IDIF) generation.

This class provides core functionality for processing image data, performing PCA, and generating IDIF-related metrics such as mean voxel time-activity curves (TACs) and PCA-based projections. The class is abstract and intended to be extended with specific methods for voxel selection or further analysis.

Variables:

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

  • mask_path (str) – Path to the mask image file used to extract regions of interest.

  • output_tac_path (str) – Path for saving the output TAC file.

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

  • verbose (bool) – Flag to enable verbose output for diagnostic purposes.

  • tac_times_in_mins (np.ndarray) – Array containing the mid-time points of each scan frame in minutes, extracted using ScanTimingInfo.

  • idif_vals (np.ndarray) – Array of IDIF values calculated from selected voxels.

  • idif_errs (np.ndarray) – Array of standard deviations of the IDIF values.

  • prj_idif_vals (np.ndarray) – PCA-projected IDIF values.

  • prj_idif_errs (np.ndarray) – PCA-projected IDIF value standard deviations.

  • pca_obj (PCA or None) – PCA object used to perform decomposition, initialized during processing.

  • pca_fit (np.ndarray or None) – Array of PCA-projected voxel representations.

  • mask_voxel_tacs (np.ndarray) – Time-activity curves (TACs) extracted from the mask region in the image.

  • mask_avg (np.ndarray) – Voxel-wise mean activity within the mask.

  • mask_std (np.ndarray) – Voxel-wise standard deviation of activity within the mask.

  • mask_peak_arg (int) – Index of the peak voxel activity in the time-activity curve.

  • mask_peak_val (float) – Value of the peak voxel activity.

  • selected_voxels_mask (np.ndarray or None) – Boolean mask of selected voxels after analysis.

  • selected_voxels_tacs (np.ndarray or float) – TACs for the selected voxels.

  • selected_voxels_prj_tacs (np.ndarray or float) – PCA-projected TACs for the selected voxels.

  • analysis_has_run (bool) – Indicates whether the analysis (typically run()) has been executed.

See also

Initializes the base class for PCA-guided IDIF generation.

This constructor sets up the necessary attributes for processing image and mask data, performing PCA decomposition, and preparing for downstream TAC and IDIF calculations.

Parameters:

  • input_image_path (str) – The file path for the dynamic 4D image used for generating the IDIF.

  • mask_image_path (str) – The file path for the mask image used to extract voxel data.

  • output_tac_path (str) – The file path where the resulting TAC data will be saved.

  • num_pca_components (int) – The number of PCA components to calculate.

  • verbose (bool) – If True, enables verbose output for intermediate steps and diagnostics.

Raises:

FileNotFoundError – If either the input image file or mask file cannot be found.

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.

abstractmethod run(*args, **kwargs)#

Abstract method to be implemented by concrete subclasses.

Parameters:

  • *args

  • **kwargs

abstractmethod __call__(*args, **kwargs)#

Abstract method to be implemented by concrete subclasses.

Should usually run the .run() method and then the .save() method to allow for easily running and saving results.

Parameters:

  • *args

  • **kwargs

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