PCAGuidedIdifBase ======================================================= .. py: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: :py:obj:`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. :ivar image_path: Path to the input dynamic image file. :vartype image_path: str :ivar mask_path: Path to the mask image file used to extract regions of interest. :vartype mask_path: str :ivar output_tac_path: Path for saving the output TAC file. :vartype output_tac_path: str :ivar num_components: Number of PCA components to compute. :vartype num_components: int :ivar verbose: Flag to enable verbose output for diagnostic purposes. :vartype verbose: bool :ivar tac_times_in_mins: Array containing the mid-time points of each scan frame in minutes, extracted using `ScanTimingInfo`. :vartype tac_times_in_mins: np.ndarray :ivar idif_vals: Array of IDIF values calculated from selected voxels. :vartype idif_vals: np.ndarray :ivar idif_errs: Array of standard deviations of the IDIF values. :vartype idif_errs: np.ndarray :ivar prj_idif_vals: PCA-projected IDIF values. :vartype prj_idif_vals: np.ndarray :ivar prj_idif_errs: PCA-projected IDIF value standard deviations. :vartype prj_idif_errs: np.ndarray :ivar pca_obj: PCA object used to perform decomposition, initialized during processing. :vartype pca_obj: PCA or None :ivar pca_fit: Array of PCA-projected voxel representations. :vartype pca_fit: np.ndarray or None :ivar mask_voxel_tacs: Time-activity curves (TACs) extracted from the mask region in the image. :vartype mask_voxel_tacs: np.ndarray :ivar mask_avg: Voxel-wise mean activity within the mask. :vartype mask_avg: np.ndarray :ivar mask_std: Voxel-wise standard deviation of activity within the mask. :vartype mask_std: np.ndarray :ivar mask_peak_arg: Index of the peak voxel activity in the time-activity curve. :vartype mask_peak_arg: int :ivar mask_peak_val: Value of the peak voxel activity. :vartype mask_peak_val: float :ivar selected_voxels_mask: Boolean mask of selected voxels after analysis. :vartype selected_voxels_mask: np.ndarray or None :ivar selected_voxels_tacs: TACs for the selected voxels. :vartype selected_voxels_tacs: np.ndarray or float :ivar selected_voxels_prj_tacs: PCA-projected TACs for the selected voxels. :vartype selected_voxels_prj_tacs: np.ndarray or float :ivar analysis_has_run: Indicates whether the analysis (typically :meth:`run`) has been executed. :vartype analysis_has_run: bool .. seealso:: - :class:`~.PCAGuidedTopVoxelsIDIF` - :class:`~.PCAGuidedIdifFitter` 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. :param input_image_path: The file path for the dynamic 4D image used for generating the IDIF. :type input_image_path: str :param mask_image_path: The file path for the mask image used to extract voxel data. :type mask_image_path: str :param output_tac_path: The file path where the resulting TAC data will be saved. :type output_tac_path: str :param num_pca_components: The number of PCA components to calculate. :type num_pca_components: int :param verbose: If True, enables verbose output for intermediate steps and diagnostics. :type verbose: bool :raises FileNotFoundError: If either the input image file or mask file cannot be found. .. py:method:: 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 :func:`~.extract_roi_voxel_tacs_from_image_using_mask` Attributes Updated: - `pca_obj` - `pca_fit` :raises ValueError: If PCA analysis fails during execution. .. py:method:: 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. :param rescale_constant: The constant factor used for rescaling. Must be greater than zero. Default is 37000.0. :type rescale_constant: float 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. .. py:method:: 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. .. py:method:: 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). .. rubric:: Notes - Negative PCA-projected IDIF values are set to zero since negative values are non-physical. .. py:method:: run(*args, **kwargs) :abstractmethod: Abstract method to be implemented by concrete subclasses. :param \*args: :param \*\*kwargs: .. py:method:: __call__(*args, **kwargs) :abstractmethod: 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. :param \*args: :param \*\*kwargs: .. py:property:: idif_tac Get the calculated IDIF TAC :returns: *TimeActivityCurve* -- TAC object with (times, idif_vals) .. seealso:: :class:`~.TimeActivityCurve` .. py:property:: idif_tac_werr Get the calculated IDIF TAC with the standard deviations :returns: *TimeActivityCurve* -- TAC object with (times, idif_vals, idif_stderrs) .. seealso:: :class:`~.TimeActivityCurve` .. py:property:: prj_idif_tac Get the calculated PCA-projected IDIF TAC :returns: *TimeActivityCurve* -- TAC object with (times, projected_idif_vals) .. seealso:: :class:`~.TimeActivityCurve` .. py: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) .. seealso:: :class:`~.TimeActivityCurve`