PCAGuidedTopVoxelsIDIF#

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: PCAGuidedIdifBase

Class for calculating a PCA-guided IDIF by averaging over the top voxels of a selected principal component (PC).

This class extends 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:

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.

Parameters:

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

  • mask_image_path (str) – Path to the mask image used for voxel selection.

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

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

  • verbose (bool) – If True, enables detailed diagnostic output.

Side Effects:

Initializes instance-specific attributes (num_of_voxels and selected_component) as None until provided during a call to run.

static calculate_top_pc_voxels_mask(pca_obj: sklearn.decomposition.PCA, pca_fit: numpy.ndarray, pca_component: int, number_of_voxels: int) → numpy.ndarray#

Determines the top contributing voxels for a specified PCA component.

Parameters:

  • pca_obj (PCA) – A scikit-learn PCA object used to compute the principal components.

  • pca_fit (np.ndarray) – The array of PCA projections for each voxel.

  • pca_component (int) – Index of the PCA component for voxel selection (0-based).

  • number_of_voxels (int) – The number of top-contributing voxels to include.

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).

Notes

Voxels are ranked and selected based on a descending sort of their contributions to the specified PCA component.

run(selected_component: int, num_of_voxels: int) → None#

Executes the PCA-guided IDIF analysis by selecting voxels and calculating TACs.

Parameters:

  • selected_component (int) – The PCA component index to guide voxel selection (0-based).

  • num_of_voxels (int) – The number of top-contributing voxels to include in the analysis.

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.

Notes

This method must be called before saving or further analyzing the results, as it sets the necessary state attributes.

__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.

Parameters:

  • selected_component (int) – The PCA component index to guide voxel selection (0-based).

  • num_of_voxels (int) – The number of top-contributing voxels to include in the analysis.

Side Effects:

  • Runs the full analysis using the run method.

  • Saves the resulting TAC data to the file specified in output_tac_path.

Notes

Combines the functionality of run and save for streamlined usage.

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