PCAGuidedTopVoxelsIDIF ============================================================ .. py:class:: petpal.input_function.pca_guided_idif.PCAGuidedTopVoxelsIDIF(input_image_path: str, mask_image_path: str, output_tac_path: str, num_pca_components: int, verbose: bool) Bases: :py:obj:`PCAGuidedIdifBase` Class for calculating a PCA-guided IDIF by averaging over the top voxels of a selected principal component (PC). This class extends :class:`~.PCAGuidedIdifBase` and specializes in selecting the most contributing voxels for a specific PCA component to refine the IDIF estimation. The user must specify the PCA component and the number of voxels to be analyzed for the calculation. Example: .. code-block:: python from petpal.input_function.pca_guided_idif import PCAGuidedTopVoxelsIDIF ## Initializing the fitting object pca_idif_top = PCAGuidedTopVoxelsIDIF(input_image_path='/path/to/4d/pet/image.nii.gz', mask_image_path='/path/to/arterial/mask.nii.gz', output_tac_path='/path/to/save/tac.tsv', num_pca_components=3, verbose=True) ## Sorting the voxels with respect to the 1st PC, and averaging over 50 voxels pca_idif_top.run(selected_component=0, num_of_voxels=50) ## Saving the IDIF TACs to disk pca_idif_top.save() Initializes the PCA-guided Top Voxels IDIF class. :param input_image_path: Path to the dynamic input image used to calculate the IDIF. :type input_image_path: str :param mask_image_path: Path to the mask image used for voxel selection. :type mask_image_path: str :param output_tac_path: Destination path where the output TAC data will be saved. :type output_tac_path: str :param num_pca_components: Number of PCA components to compute. :type num_pca_components: int :param verbose: If True, enables detailed diagnostic output. :type verbose: bool Side Effects: Initializes instance-specific attributes (`num_of_voxels` and `selected_component`) as `None` until provided during a call to `run`. .. py:method:: calculate_top_pc_voxels_mask(pca_obj: sklearn.decomposition.PCA, pca_fit: numpy.ndarray, pca_component: int, number_of_voxels: int) -> numpy.ndarray :staticmethod: Determines the top contributing voxels for a specified PCA component. :param pca_obj: A scikit-learn PCA object used to compute the principal components. :type pca_obj: PCA :param pca_fit: The array of PCA projections for each voxel. :type pca_fit: np.ndarray :param pca_component: Index of the PCA component for voxel selection (0-based). :type pca_component: int :param number_of_voxels: The number of top-contributing voxels to include. :type number_of_voxels: int :returns: *np.ndarray* -- A Boolean mask indicating the voxels selected for the specified PCA component. :raises AssertionError: If the `pca_component` index is invalid (e.g., less than 0 or greater than or equal to the number of PCA components in `pca_obj`). .. rubric:: Notes Voxels are ranked and selected based on a descending sort of their contributions to the specified PCA component. .. py:method:: run(selected_component: int, num_of_voxels: int) -> None Executes the PCA-guided IDIF analysis by selecting voxels and calculating TACs. :param selected_component: The PCA component index to guide voxel selection (0-based). :type selected_component: int :param num_of_voxels: The number of top-contributing voxels to include in the analysis. :type num_of_voxels: int Side Effects: - Sets `selected_component` to the chosen PCA component index. - Sets `num_of_voxels` to the number of selected voxels. - Updates `selected_voxels_mask` with a mask indicating top-contributing voxels. - Marks `analysis_has_run` as True after successful execution. - Updates IDIF-related metrics (e.g., `idif_vals`, `prj_idif_vals`) by invoking `calculate_tacs_from_mask`. :raises AssertionError: If `num_of_voxels` is less than 3. .. rubric:: Notes This method must be called before saving or further analyzing the results, as it sets the necessary state attributes. .. py:method:: __call__(selected_component: int, num_of_voxels: int) -> None Callable interface for running the analysis and saving the results. This method provides a convenient way to execute the analysis and save the resultant TAC data to the specified output file in a single call. :param selected_component: The PCA component index to guide voxel selection (0-based). :type selected_component: int :param num_of_voxels: The number of top-contributing voxels to include in the analysis. :type num_of_voxels: int Side Effects: - Runs the full analysis using the `run` method. - Saves the resulting TAC data to the file specified in `output_tac_path`. .. rubric:: Notes Combines the functionality of `run` and `save` for streamlined usage. .. 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: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`