coronalyze.analysis.yields
==========================

.. py:module:: coronalyze.analysis.yields

.. autoapi-nested-parse::

   Simplified analysis tools for yield modeling and noise floor estimation.

   Implements 'Faux-RDI' and related tools for yield calculations where we assume
   perfect knowledge of the background model (stellar speckles + disk).



Functions
---------

.. autoapisummary::

   coronalyze.analysis.yields.get_perfect_residuals
   coronalyze.analysis.yields.get_photon_noise_map
   coronalyze.analysis.yields.simulate_observation


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

.. py:function:: get_perfect_residuals(observation, expectation_model)

   Calculate residuals assuming perfect subtraction of static structure.

   This simulates 'Faux-RDI': we subtract the exact expectation value of
   the star and disk. The residual contains only the fundamental noise
   (photon + read noise) and any signals not in the model (planets).

   Args:
       observation: The noisy data (Data = Poisson(Model) + ReadNoise).
       expectation_model: The noiseless expectation of background sources
           (stellar PSF + disk, excluding planets).

   Returns:
       Residual image containing noise + unmodeled signals (planets).


.. py:function:: get_photon_noise_map(expectation_rate, exposure_time, read_noise = 0.0)

   Calculate the theoretical 1-sigma noise map in rate units.

   Properly converts between rate and count units to combine photon noise
   with read noise. Returns noise in the same units as input (counts/sec).

   Formula: Sigma_rate = sqrt(Rate * t + RN^2) / t

   Args:
       expectation_rate: Expected count rate image (counts/sec).
       exposure_time: Integration time in seconds.
       read_noise: Read noise in electrons (per pixel). Default 0.

   Returns:
       1-sigma noise map in rate units (counts/sec), same shape as input.


.. py:function:: simulate_observation(clean_signal, background_model, exposure_time = 1.0, rng_key = None)

   Generate a noisy realization of the scene for yield tests.

   Applies Poisson noise to the combined scene (signal + background).
   Returns data in rate units (counts/sec).

   Args:
       clean_signal: Planet image (counts/sec).
       background_model: Star + Disk expectation (counts/sec).
       exposure_time: Integration time (seconds).
       rng_key: JAX PRNG Key. If None, uses key 0.

   Returns:
       Noisy image in units of counts/sec (Poisson noise added in counts,
       then divided back by exposure time).