Pca Guided Idif Steps
=====================

.. py:module:: petpal.pipelines.pca_guided_idif_steps

.. autoapi-nested-parse::

   This module provides classes and utilities for computing Image-Derived Input Functions
   (IDIF) using a PCA-guided approach. It is designed to integrate into preprocessing pipelines
   and offers functionality for optimizing voxel selection, applying fitting techniques,
   and selecting top-ranked voxels from PCA components.

   Classes:
   --------

   1. :class:`PCAGuidedIDIFMixin`:
       - Acts as a mixin to provide shared functionality across PCA-guided steps.
       - Manages input/output paths, initializes configurations, and helps connect pipeline steps.
       - Provides methods to infer output paths and set input paths dynamically.

   2. :class:`PCAGuidedFitIDIFStep`:
       - Represents a pipeline step for optimizing voxel selection to fit the IDIF using PCA-guided methods.
       - Extends both :class:`~.ObjectBasedStep` and :class:`~.PCAGuidedIDIFMixin` to integrate optimization fitting into a pipeline.
       - Includes parameters to control optimization behavior, such as:
           - **alpha**: Weight for the peak term to encourage a high TAC peak.
           - **beta**: Weight for the smoothness term to ensure low total variation.
           - **method**: The optimization method for fitting.

   3. :class:`PCAGuidedTopVoxelsIDIFStep`:
       - Represents a pipeline step to calculate the IDIF by selecting the top `N` voxels from a specific PCA component.
       - Extends both :class:`~.ObjectBasedStep` and :class:`~.PCAGuidedIDIFMixin` for pipeline functionality.
       - Allows customizing the selected PCA component and the number of voxels to include.

   Key Features:
   -------------
   - **Pipeline Integration**:
       All classes are designed to be modular and compatible with preprocessing pipelines.
       They inherit functionalities from :class:`~.ObjectBasedStep` and :class:`~.StepsAPI`.

   - **BIDS-Compatible Output**:
       Output paths for TAC files are generated in a BIDS-like format using subject and session information
       extracted from the input image paths.

   - **Optimization and Voxel Selection**:
       Classes include functionality to:
           - Select voxels based on PCA component ranking.
           - Optimize voxel selection iteratively for better IDIF calculation.
           - Use terms like smoothness, noise reduction, and peak emphasis for guiding optimization.




Classes
-------

.. toctree::
   :hidden:

   /autoapi/petpal/pipelines/pca_guided_idif_steps/PCAGuidedIDIFMixin
   /autoapi/petpal/pipelines/pca_guided_idif_steps/PCAGuidedFitIDIFStep
   /autoapi/petpal/pipelines/pca_guided_idif_steps/PCAGuidedTopVoxelsIDIFStep

.. autoapisummary::

   petpal.pipelines.pca_guided_idif_steps.PCAGuidedIDIFMixin
   petpal.pipelines.pca_guided_idif_steps.PCAGuidedFitIDIFStep
   petpal.pipelines.pca_guided_idif_steps.PCAGuidedTopVoxelsIDIFStep