PCAGuidedIdifFitter#

class petpal.input_function.pca_guided_idif.PCAGuidedIdifFitter(input_image_path: str, mask_image_path: str, output_tac_path: str, num_pca_components: int, pca_comp_filter_min_value: float = 0.0, pca_comp_threshold: float = 0.1, verbose: bool = False)#

Bases: PCAGuidedIdifFitterBase

Class to calculate the PCA-guided Image-Derived Input Function (IDIF) by fitting to find the best voxels.

This class extends PCAGuidedIdifFitterBase and implements domain-specific functions to guide the optimization process, including terms for voxel count, noise reduction, smoothness enforcement, and peak emphasis. The optimization aims to refine the voxel selection for IDIF estimation using the provided fitting terms.

Example

from petpal.input_function.pca_guided_idif import PCAGuidedIdifFitter

## Initializing the fitting object
pca_idif_fit = PCAGuidedIdifFitter(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,
                                   pca_comp_filter_min_value=0.0,
                                   pca_comp_threshold=0.1,
                                   verbose=True)

## Running the fitting with the dual_annealing minimization method
pca_idif_fit.run(alpha=2.5,
                 beta=0.0,
                 method='dual_annealing')

## Saving the IDIF TACs to disk
pca_idif_fit.save()

Initializes the PCA-guided IDIF fitter.

Parameters:

input_image_path (str) – Path to the input dynamic image used for IDIF estimation.
mask_image_path (str) – Path to the mask image for selecting the region of interest.
output_tac_path (str) – Path where the calculated TAC data will be saved.
num_pca_components (int) – Number of PCA components to compute for voxel selection.
pca_comp_filter_min_value (float, optional) – Minimum value for filtering PCA components (default: 0.0).
pca_comp_threshold (float, optional) – Threshold for filtering PCA components (default: 0.1).
verbose (bool, optional) – Enables detailed diagnostic output if set to True (default: False).

Side Effects:

Calls the base class constructor to initialize parameters and fit-related attributes.

static _voxel_term_func(voxel_nums: float) → float#

A softplus function to encourage optimization toward selecting more voxels.

This term penalizes scenarios where fewer voxels are selected by incrementally rewarding configurations with larger voxel numbers.

Notes

Applies the softplus function defined as \(\ln\left(1+e^{v/6}\right)\) where \(v\) is the number of voxels.

Parameters:: voxel_nums (float) – The number of voxels contributing to the TAC.
Returns:: float – The calculated voxel term value.

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

Root-mean-square (RMS) noise term to favor voxels with reduced per-frame variance.

This term penalizes higher noise levels in the selected voxels’ TAC data, rewarding smoother per-frame signal averages.

Notes

The noise term is computed as \(\sqrt{\frac{1}{n}\sum_{i}^{n}{\sigma_i}^2}\), where \(\sigma_i\) is the per-frame standard deviation, and \(n\) is the number of frames.

Parameters:: tac_stderrs (np.ndarray[float]) – The array of standard errors of the mean (SEM) for the TAC.
Returns:: float – The calculated noise term value.

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

Smoothness term enforcing total variation consistency on the TAC values.

This term penalizes abrupt changes in frame-to-frame TAC values by calculating the L1-norm of differences in TAC values. It helps ensure smoother TACs from the selected voxels.

Notes

Defined as the sum of absolute differences in normalized TAC values: \(\frac{\beta}{c_\mathrm{max}}\sum_{i}^{n}{\left|c_{i+1} - c_{i}\right|}\) where \(\beta\) is a tuning parameter, and \(n\) is the number of frames.

Parameters:: tac_values (np.ndarray[float]) – The TAC values obtained from the selected voxels.
Returns:: float – The calculated smoothness term value.

static _peak_term_func(tac_peak_ratio: float) → float#

Peak term driving the TAC peak value to be sufficiently high.

This term rewards configurations where the TAC has a pronounced peak relative to its baseline, as higher peaks often correlate with improved IDIF estimates.

Notes

Applies the softplus function defined as \(\alpha \times\ln\left(1+e^{-\frac{3}{2}r}\right)\) where \(\alpha\) is the tuning parameter, and \(r\) is the ratio of the value of the computed TAC to the value of the average TAC of the mask.

Parameters:: tac_peak_ratio (float) – The ratio of the TAC peak value to a reference value.
Returns:: float – The calculated peak term value.

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 _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

PCAGuidedIdifFitter#

This Page