coronalyze.core.pca
===================

.. py:module:: coronalyze.core.pca

.. autoapi-nested-parse::

   Principal Component Analysis (PCA/KLIP) for PSF subtraction.

   Implements the efficient 'Snapshot Method' for SVD on large image cubes,
   particularly suited for coronagraphy (where pixels >> frames).
   All functions are JIT-compilable and fully differentiable.



Functions
---------

.. autoapisummary::

   coronalyze.core.pca.get_pca_basis
   coronalyze.core.pca.pca_subtract


Module Contents
---------------

.. py:function:: get_pca_basis(ref_cube, n_modes)

   Compute PCA basis vectors from a reference cube (Snapshot Method).

   Uses eigendecomposition of the NxN covariance matrix instead of full SVD,
   which is O(N²xP) vs O(P²xN) for pixels P >> frames N.

   Args:
       ref_cube: Reference image cube of shape (N_frames, Height, Width).
       n_modes: Number of principal components (modes) to keep.

   Returns:
       basis: The top n_modes eigen-images, shape (n_modes, Height*Width).
       mean_ref: The mean of the reference cube, shape (Height, Width).


.. py:function:: pca_subtract(science_image, basis, mean_ref)

   Project science image onto PCA basis and subtract the model.

   Args:
       science_image: 2D science image, shape (Height, Width).
       basis: PCA basis from get_pca_basis, shape (n_modes, Height*Width).
       mean_ref: Mean reference from get_pca_basis, shape (Height, Width).

   Returns:
       Residual image with PSF model subtracted, shape (Height, Width).