PCAGuidedFitIDIFStep =========================================================== .. py: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: :py:obj:`petpal.pipelines.steps_base.ObjectBasedStep`, :py:obj:`PCAGuidedIDIFMixin` Pipeline step for fitting the PCA-guided IDIF using an optimization-based approach. This step extends the :class:`~.PCAGuidedIDIFMixin` for shared functionality and the :class:`~.ObjectBasedStep` for pipeline execution. It uses the :class:`~.PCAGuidedIdifFitter` class to iteratively optimize voxel selection for IDIF generation based on specified parameters. Inheritance: Inherits from :class:`~.ObjectBasedStep` and :class:`~.PCAGuidedIDIFMixin`. :ivar alpha: Parameter weight for the peak term (emphasizes high TAC peaks). :vartype alpha: float :ivar beta: Parameter weight for the smoothness term (encourages smoother signals). :vartype beta: float :ivar method: Optimization method to be used during fitting. :vartype method: str .. rubric:: Example .. code-block:: python 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. :param input_image_path: Path to the input 4D-PET image. :type input_image_path: str :param mask_image_path: Path to the mask image in the same space as 4D-PET image. :type mask_image_path: str :param output_array_path: Path where the resulting TAC data will be saved. :type output_array_path: str :param num_pca_components: Number of PCA components to consider. :type num_pca_components: int :param verbose: If `True`, enables detailed diagnostic output. :type verbose: bool :param alpha: Parameter weight for the peak term. :type alpha: float :param beta: Parameter weight for the smoothness term. :type beta: float :param method: Optimization method to use for fitting. :type method: str :param \*\*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. .. py:property:: alpha .. py:property:: beta .. py:property:: method .. py:method:: default_pca_guided_idif_fit(name: str = 'pca_guided_fit_idif', verbose=False, **overrides) :classmethod: Creates a default instance for PCA-guided IDIF calculation using an optimization-based fitting approach. Uses :class:`~.pca_guided_idif.PCAGuidedIdifFitter` All file paths are set to empty strings by default. :param name: Name of the step. Defaults to 'pca_guided_fit_idif'. :type name: str :param verbose: Whether to enable verbose mode (default: False). :type verbose: bool :param \*\*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. .. py:method:: validate_kwargs() Validates that all mandatory initialization and call arguments have been provided. :raises RuntimeError: If any mandatory arguments are missing. .. py:method:: get_args_not_set_in_kwargs(sig: inspect.Signature, kwargs: dict) -> dict :staticmethod: Retrieves arguments of the signature that are not set in the keyword arguments. :param sig: The signature of the function or method. :type sig: inspect.Signature :param kwargs: The keyword arguments provided. :type kwargs: dict :returns: *dict* -- A dictionary of arguments that are not set in the keyword arguments. .. py:method:: get_empty_default_kwargs(sig: inspect.Signature, set_kwargs: dict) -> list Identifies arguments that have not been provided and lack default values. :param sig: The signature of the function or method. :type sig: inspect.Signature :param set_kwargs: The keyword arguments provided. :type set_kwargs: dict :returns: *list* -- A list of argument names that have no default values and are not provided. .. py:method:: execute() -> None Instantiates the class and invokes it with the provided arguments. :raises The function may raise any exceptions that its implementation can throw.: .. py:method:: __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. .. py:method:: __repr__() Returns an unambiguous string representation of the ObjectBasedStep instance. :returns: *str* -- A string representation showing how the ObjectBasedStep can be recreated. .. py:method:: 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. .. py:method:: 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. .. py:method:: 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. .. py:method:: set_input_as_output_from(*sending_steps) :abstractmethod: Sets the input of the current step as the output from a list of steps. :param \*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. .. rubric:: Notes For a concrete example, take a look at: :meth:`TACsFromSegmentationStep` .. important:: If a step takes multiple input steps. the implementation will have a defined order for steps. .. py:method:: infer_outputs_from_inputs(out_dir: str, der_type: str, suffix: str = None, ext: str = None, **extra_desc) :abstractmethod: Infers output files from input data based on the specified output directory, derivative type, optional suffix and extension, plus any extra descriptions. :param out_dir: The directory where the output files will be saved. :type out_dir: str :param der_type: The type of derivative being produced. :type der_type: str :param suffix: An optional suffix for the output files. :type suffix: str, optional :param ext: An optional extension for the output files. :type ext: str, optional :param \*\*extra_desc: Additional keyword arguments for extra descriptions to be included. :raises NotImplementedError: This method should be implemented by subclasses. .. rubric:: Notes For a concrete example, take a look at: :meth:`TACsFromSegmentationStep` .. py:method:: __call__(*args, **kwargs) .. py:property:: input_image_path .. py:property:: mask_image_path .. py:property:: output_tac_path :type: str .. py:property:: num_pca_components .. py:property:: verbose