PCAGuidedFitIDIFStep#

class petpal.pipelines.pca_guided_idif_steps.PCAGuidedFitIDIFStep(input_image_path: str, mask_image_path: str, output_array_path: str, num_pca_components: int, verbose: bool, alpha: float, beta: float, method: str, **meth_kwargs)#

Bases: petpal.pipelines.steps_base.ObjectBasedStep, PCAGuidedIDIFMixin

Pipeline step for fitting the PCA-guided IDIF using an optimization-based approach.

This step extends the PCAGuidedIDIFMixin for shared functionality and the ObjectBasedStep for pipeline execution. It uses the PCAGuidedIdifFitter class to iteratively optimize voxel selection for IDIF generation based on specified parameters.

Inheritance:

Inherits from ObjectBasedStep and PCAGuidedIDIFMixin.

Variables:

  • alpha (float) – Parameter weight for the peak term (emphasizes high TAC peaks).

  • beta (float) – Parameter weight for the smoothness term (encourages smoother signals).

  • method (str) – Optimization method to be used during fitting.

Example

from petpal.pipelines.pca_guided_idif_steps import PCAGuidedFitIDIFStep

step = PCAGuidedFitIDIFStep(input_image_path='/path/to/image.nii',
                            mask_image_path='/path/to/mask.nii',
                            output_array_path='/path/to/output.tsv',
                            num_pca_components=5,
                            verbose=True,
                            alpha=0.5,
                            beta=0.3,
                            method='ampgo')
## Running and saving the results
step()  # Executes the step

Initializes the PCA-guided fitting IDIF step.

Parameters:

  • input_image_path (str) – Path to the input 4D-PET image.

  • mask_image_path (str) – Path to the mask image in the same space as 4D-PET image.

  • output_array_path (str) – Path where the resulting TAC data will be saved.

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

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

  • alpha (float) – Parameter weight for the peak term.

  • beta (float) – Parameter weight for the smoothness term.

  • method (str) – Optimization method to use for fitting.

  • **meth_kwargs – Additional keyword arguments for the optimization method.

Side Effects:

  • Initializes python-guided-idif fitter with the provided parameters.

  • Populates call_kwargs with runtime-specific options for the fitting process.

property alpha#
property beta#
property method#
classmethod default_pca_guided_idif_fit(name: str = 'pca_guided_fit_idif', verbose=False, **overrides)#

Creates a default instance for PCA-guided IDIF calculation using an optimization-based fitting approach.

Uses PCAGuidedIdifFitter

All file paths are set to empty strings by default.

Parameters:

  • name (str) – Name of the step. Defaults to ‘pca_guided_fit_idif’.

  • verbose (bool) – Whether to enable verbose mode (default: False).

  • **overrides – Parameter values to override the default settings.

Returns:

PCAGuidedFitIDIFStep – A new instance of the PCA-guided IDIF fitting step.

Default Parameters:

  • input_image_path: ‘’ (empty string)

  • mask_image_path: ‘’ (empty string)

  • output_array_path: ‘’ (empty string)

  • num_pca_components: 3

  • verbose: False

  • alpha: 2.5

  • beta: 0.0

  • method: ‘dual_annealing’

Side Effects:

  • If an invalid override is provided, a warning is issued, and the default instance is returned instead.

validate_kwargs()#

Validates that all mandatory initialization and call arguments have been provided.

Raises:

RuntimeError – If any mandatory arguments are missing.

static get_args_not_set_in_kwargs(sig: inspect.Signature, kwargs: dict) → dict#

Retrieves arguments of the signature that are not set in the keyword arguments.

Parameters:

  • sig (inspect.Signature) – The signature of the function or method.

  • kwargs (dict) – The keyword arguments provided.

Returns:

dict – A dictionary of arguments that are not set in the keyword arguments.

get_empty_default_kwargs(sig: inspect.Signature, set_kwargs: dict) → list#

Identifies arguments that have not been provided and lack default values.

Parameters:

  • sig (inspect.Signature) – The signature of the function or method.

  • set_kwargs (dict) – The keyword arguments provided.

Returns:

list – A list of argument names that have no default values and are not provided.

execute() → None#

Instantiates the class and invokes it with the provided arguments.

Raises:

The function may raise any exceptions that its implementation can throw. –

__str__()#

Returns a detailed string representation of the ObjectBasedStep instance.

Returns:

str – A string describing the step, including its name, class, initialization, and call arguments.

__repr__()#

Returns an unambiguous string representation of the ObjectBasedStep instance.

Returns:

str – A string representation showing how the ObjectBasedStep can be recreated.

all_init_kwargs_non_empty_strings()#

Checks if all initialization keyword arguments are non-empty strings.

Returns:

bool – True if all initialization keyword arguments are non-empty strings, False otherwise.

all_call_kwargs_non_empty_strings()#

Checks if all call keyword arguments are non-empty strings.

Returns:

bool – True if all call keyword arguments are non-empty strings, False otherwise.

can_potentially_run()#

Determines if the step can potentially be executed based on argument validation. Very simply checks if all __init__ and __call__ keyword arguments for the object are non-empty strings.

Returns:

bool – True if the step can potentially run, False otherwise.

abstractmethod set_input_as_output_from(*sending_steps)#

Sets the input of the current step as the output from a list of steps.

Parameters:

*sending_steps – The previous steps from which the output will be used as input for the current step.

Raises:

NotImplementedError – This method should be implemented by subclasses.

Notes

For a concrete example, take a look at: TACsFromSegmentationStep

Important

If a step takes multiple input steps. the implementation will have a defined order for steps.

abstractmethod infer_outputs_from_inputs(out_dir: str, der_type: str, suffix: str = None, ext: str = None, **extra_desc)#

Infers output files from input data based on the specified output directory, derivative type, optional suffix and extension, plus any extra descriptions.

Parameters:

  • out_dir (str) – The directory where the output files will be saved.

  • der_type (str) – The type of derivative being produced.

  • suffix (str, optional) – An optional suffix for the output files.

  • ext (str, optional) – An optional extension for the output files.

  • **extra_desc – Additional keyword arguments for extra descriptions to be included.

Raises:

NotImplementedError – This method should be implemented by subclasses.

Notes

For a concrete example, take a look at: TACsFromSegmentationStep

__call__(*args, **kwargs)#
property input_image_path#
property mask_image_path#
property output_tac_path: str#
property num_pca_components#
property verbose#