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

.. py:module:: petpal.input_function.pca_guided_idif

.. autoapi-nested-parse::

   This module implements PCA (Principal Component Analysis)-guided methods for generating
   Image-Derived Input Functions (IDIF) from 4D-PET data. IDIFs are used in PET
   (Positron Emission Tomography) imaging workflows for kinetic modeling and quantification.
   The methods provided in this module focus on data-driven approaches based on PCA, offering
   tools for selecting relevant voxels and refining input functions.

   The module is designed for flexibility, offering tools for to apply PCA-based analyses over
   4D-PET data and masks. The classes are structured to allow reuse and extension for new functionalities.

   Classes
   -------
   - :class:`PCAGuidedIdifBase`: An abstract base class that supports data preparation, PCA operations,
     and IDIF computation from PCA projections.
   - :class:`PCAGuidedTopVoxelsIDIF`: Implements IDIF generation based on selecting the top PCA component
     voxels.
   - :class:`PCAGuidedIdifFitterBase`: A base class for deriving optimal voxel fit masks using minimization
     routines and customizable terms (e.g., smoothness, noise).
   - :class:`PCAGuidedIdifFitter`: A concrete implementation of :class:`PCAGuidedIdifFitterBase`, providing
     default term definitions.

   Dependencies
   ------------
   - :mod:`numpy`: For numerical operations and array manipulations.
   - :mod:`ants`: For reading and handling medical image data.
   - :mod:`lmfit`: Used for robust fitting and parameter optimization.
   - :mod:`sklearn`: For PCA implementation.
   - Other project-specific utilities:
       - :class:`~.ScanTimingInfo`: Handles timing information from NIfTI images.
       - :func:`~.temporal_pca_analysis_of_image_over_mask`: Performs PCA on dynamic image data over a given mask.
       - :func:`~.extract_roi_voxel_tacs_from_image_using_mask`: Extracts voxel TACS (Time-Activity Curves) from the input image.

   .. rubric:: Notes

   - The classes contain abstract (``NotImplementedError``) methods, intended to be overridden by derived
     classes as per the specific use case. These serve as stubs for users wishing to extend the module.
   - While the module supports large dynamic datasets, care should be taken with memory usage when
     handling large voxel masks or PCA decomposition.

   .. todo:: -   Write a tutorial to to use the class to generate an IDIF and use the IF to perform kinetic analysis




Classes
-------

.. toctree::
   :hidden:

   /autoapi/petpal/input_function/pca_guided_idif/PCAGuidedIdifBase
   /autoapi/petpal/input_function/pca_guided_idif/PCAGuidedTopVoxelsIDIF
   /autoapi/petpal/input_function/pca_guided_idif/PCAGuidedIdifFitterBase
   /autoapi/petpal/input_function/pca_guided_idif/PCAGuidedIdifFitter

.. autoapisummary::

   petpal.input_function.pca_guided_idif.PCAGuidedIdifBase
   petpal.input_function.pca_guided_idif.PCAGuidedTopVoxelsIDIF
   petpal.input_function.pca_guided_idif.PCAGuidedIdifFitterBase
   petpal.input_function.pca_guided_idif.PCAGuidedIdifFitter