pysersic.loss
=============

.. py:module:: pysersic.loss


Functions
---------

.. autoapisummary::

   pysersic.loss.gaussian_loss
   pysersic.loss.cash_loss
   pysersic.loss.gaussian_loss_w_frac
   pysersic.loss.gaussian_loss_w_sys
   pysersic.loss.student_t_loss
   pysersic.loss.student_t_loss_free_sys
   pysersic.loss.pseudo_huber_loss
   pysersic.loss.gaussian_mixture
   pysersic.loss.gaussian_mixture_w_sys
   pysersic.loss.gaussian_mixture_w_frac


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

.. py:function:: gaussian_loss(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, suffix: str = '') -> float

   Basic Gaussian loss function using given uncertainties

   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: cash_loss(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, suffix: str = '') -> float

   Cash statistic based on Poisson statistics derived in Cash (1979) (DOI 10.1086/156922) and advocated for in Erwin (2015) (https://arxiv.org/abs/1408.1097) for use in Sersic fitting. Since the is based on Poisson statistics, scaling of the image will produce different confidence intervals. Additionally, since a logarithm is taken of the model image, negative values associated with different sky models will cause issues.

   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: gaussian_loss_w_frac(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, suffix: str = '') -> float

   Gaussian loss with and additional fractional increase to all uncertainties such that,

   $$ \sigma_{new,i} = (1 + f) * \sigma_{old,i} $$

   f is a free parameter varied between -0.5 and 2

   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: gaussian_loss_w_sys(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, suffix: str = '') -> float

   Gaussian loss with and additional systematic increase such_that

   $$ \sigma_{new,i}^2 = \sigma_{old,i}^2 + \sigma_{sys}^2 $$

   \sigma_{sys} is a free parameter with a Normal prior, with loc = 0 and scale = mean(rms) truncated to ensure > 0

   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: student_t_loss(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, nu: Optional[int] = 5, suffix: str = '') -> float

   Student T loss, with a df = 5 by default. This has fatter tails than Gaussian loss (or chi squared) so is more resilient to outliers

   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: student_t_loss_free_sys(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, nu: Optional[int] = 5, suffix: str = '') -> float

   Student T loss, which has fatter tails than Gaussian loss (or chi squared) so is so is more resilient to outliers. In addition, add additional systematic increase such that

   $$ \sigma_{new,i}^2 = \sigma_{old,i}^2 + \sigma_{sys}^2 $$

   \sigma_{sys} is a free parameter with a Normal prior, with loc = 0 and scale = mean(rms) truncated to ensure > 0


   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: pseudo_huber_loss(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, delta: Optional[int] = 3, suffix: str = '') -> float

   Pseudo huber loss function of the form:

   $$ L = \delta^2 * ( \sqrt{1 + (a/\delta)^2} - 1) $$

   where a is the residuals scaled by the rms and delta can be chosen. This loss function is more robust to outliers than the Gaussian loss function as it is meant to transition for L2 to L1 loss at residuals greater than delta. The delta parameter is 3 by default but can be varied.

   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array

   :returns: Sampled loss function
   :rtype: float


.. py:function:: gaussian_mixture(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, c: Optional[float] = 5.0, suffix: str = '') -> float

   Gaussian mixture loss function, with one representing a "contaminating" outlier distribution with standard deviation equal to c*rms where c is 5 by default. The "contaminating fraction" or fraction of outliers is a free parameter with a Uniform prior between 0 and 0.25.


   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array
   :param c: factor to increase rms for outlier distribution, by default 5
   :type c: float, optional

   :returns: _description_
   :rtype: float


.. py:function:: gaussian_mixture_w_sys(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, c: Optional[float] = 5.0, suffix: str = '') -> float

   Gaussian mixture loss function, with one representing a "contaminating" outlier distribution with standard deviation equal to c*rms where c is 5 by default. The "outlier fraction" or fraction of outliers is a free parameter with a Uniform prior between 0 and 0.25.


   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array
   :param c: factor to increase rms for outlier distribution, by default 5
   :type c: float, optional

   :returns: _description_
   :rtype: float


.. py:function:: gaussian_mixture_w_frac(mod: jax.numpy.array, data: jax.numpy.array, rms: jax.numpy.array, mask: jax.numpy.array, c: Optional[float] = 5.0, suffix: str = '') -> float

   Gaussian mixture loss function, with one representing a "contaminating" outlier distribution with standard deviation equal to c*rms where c is 5 by default. The "outlier fraction" or fraction of outliers is a free parameter with a Uniform prior between 0 and 0.25.


   :param mod: Model image
   :type mod: jnp.array
   :param data: data to be fit
   :type data: jnp.array
   :param rms: per pixel 1-sigma uncertainties
   :type rms: jnp.array
   :param c: factor to increase rms for outlier distribution, by default 5
   :type c: float, optional

   :returns: _description_
   :rtype: float