opticam.noise
=============

.. py:module:: opticam.noise


Functions
---------

.. autoapisummary::

   opticam.noise.get_source_photons
   opticam.noise.get_sky_photons_per_pixel
   opticam.noise.get_sky_stderr
   opticam.noise.get_shot_stderr
   opticam.noise.get_dark_stderr
   opticam.noise.get_read_stderr
   opticam.noise.snr
   opticam.noise.snr_stderr
   opticam.noise.get_noise_params
   opticam.noise.get_snrs
   opticam.noise.characterise_noise


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

.. py:function:: get_source_photons(N_source, gain)

   Get the number of source photons.

   Parameters
   ----------
   N_source : float | NDArray
       The number of source counts.
   gain : float
       The gain.

   Returns
   -------
   float
       The number of source photons.


.. py:function:: get_sky_photons_per_pixel(n_sky, gain)

   Get the number of sky photons per pixel.

   Parameters
   ----------
   n_sky : float
       The sky counts per pixel.
   gain : float
       The gain.

   Returns
   -------
   float
       The number of sky photons per pixel.


.. py:function:: get_sky_stderr(N_source, N_pix, n_sky, gain)

   Get the standard error (in magnitudes) of the sky noise.

   Parameters
   ----------
   N_source : float
       The total number of source counts.
   N_pix : int
       The number of aperture pixels.
   n_sky : float
       The number of sky counts **per pixel**.
   gain: float
       The detector gain.

   Returns
   -------
   float
       The standard error (in magnitudes) of the sky noise.


.. py:function:: get_shot_stderr(N_source, gain)

   Get the standard error (in magnitudes) of the shot noise.

   Parameters
   ----------
   N_source : float
       The total number of source counts.
   gain: float
       The detector gain.

   Returns
   -------
   float
       The standard error (in magnitudes) of the shot noise.


.. py:function:: get_dark_stderr(N_source, N_pix, dark_flux, gain)

   Get the standard error (in magnitudes) of the dark current noise.

   Parameters
   ----------
   N_source : Quantity
       The total number of source counts.
   N_pix : int
       The number of aperture pixels.
   dark_curr : Quantity
       The number of dark current electrons **per pixel per unit time**. 
   t_exp: Quantity
       The exposure time.
   gain: Quantity
       The detector gain.

   Returns
   -------
   float
       The standard error (in magnitudes) of the dark current noise.


.. py:function:: get_read_stderr(N_source, N_pix, gain)

   Get the standard error (in magnitudes) of the readout noise.

   Parameters
   ----------
   N_source : float
       The total number of source counts.
   N_pix : float
       The number of aperture pixels.
   gain: float
       The detector gain.

   Returns
   -------
   float
       The standard error (in magnitudes) of the readout noise.


.. py:function:: snr(N_source, N_pix, n_sky, dark_flux, gain)

   The (simplified) S/N ratio equation or CCD Equation (see Chapter 4.4 of Handbook of CCD Astronomy by Howell, 2006).

   Parameters
   ----------
   N_source : float | NDArray
       The total number of source counts.
   N_pix : int
       The number of aperture pixels.
   n_sky : float
       The number of sky counts **per pixel**.
   dark_flux : float
       The dark current's "flux" contribution per pixel.
   gain: float
       The detector gain.

   Returns
   -------
   float | NDArray
       The S/N ratio.


.. py:function:: snr_stderr(N_source, N_pix, n_sky, dark_flux, gain)

   The standard error (in magnitudes) on the CCD Equation (see Chapter 4.4 of Handbook of CCD Astronomy by Howell, 
   2006).

   Parameters
   ----------
   N_source : float | NDArray
       The total number of source counts.
   N_pix : float
       The number of aperture pixels.
   n_sky : float
       The number of sky counts **per pixel**.
   dark_flux : float
       The dark current's "flux" contribution per pixel.
   gain: float
       The detector gain.

   Returns
   -------
   float | NDArray
       The standard error (in magnitudes) on the S/N ratio.


.. py:function:: get_noise_params(file, catalog, background, psf_params)

   Get the noise values of a science image.

   Parameters
   ----------
   file : str
       The path to the science image.
   catalog : QTable
       The source catalog corresponding to the science image.
   background : BaseBackground | Callable
       The background estimator.
   psf_params : Dict[str, float]
       The PSF parameters.

   Returns
   -------
   Tuple[NDArray, NDArray, float, float, float, float]
       The fluxes, flux errors, number of aperture pixels, backgorund counts/pixel, dark flux, and gain.


.. py:function:: get_snrs(file, background, catalog, psf_params)

   Get the S/N ratios for the cataloged sources in a science image.

   Parameters
   ----------
   file : str
       The path to the science image.
   background : BaseBackground | Callable
       The background estimator.
   catalog : QTable
       The source catalog corresponding to the science image.
   psf_params : Dict[str, float]
       The PSF parameters.

   Returns
   -------
   NDArray
       The S/N for each source. Sources are ordered as they appear in `catalog`.


.. py:function:: characterise_noise(file, background, catalog, psf_params)

   Characterise the expected noise from an image and compare it to the measured noise for a number of cataloged 
   sources.

   Parameters
   ----------
   file : str
       The file path to the science image.
   background : BaseBackground | Callable
       The background estimator.
   catalog : QTable
       The source catalog corresponding to the science image.
   psf_params : Dict[str, float]
       The PSF parameters.

   Returns
   -------
   Dict[str, NDArray]
       The noies properties.