coronalyze.core.statistics
==========================

.. py:module:: coronalyze.core.statistics

.. autoapi-nested-parse::

   Statistical functions for masked arrays and small-sample corrections.

   Implements JAX-native masked statistics and the Mawet et al. (2014)
   small-sample penalty for high-contrast imaging SNR calculations.



Functions
---------

.. autoapisummary::

   coronalyze.core.statistics.masked_mean
   coronalyze.core.statistics.masked_std
   coronalyze.core.statistics.small_sample_penalty


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

.. py:function:: masked_mean(values, mask)

   Compute the mean of masked values.

   Args:
       values: 1D array of values.
       mask: Boolean mask (True for valid values).

   Returns:
       Mean of valid values, or 0 if no valid values.


.. py:function:: masked_std(values, mask, mean = None)

   Compute the standard deviation of masked values.

   Uses Bessel's correction (N-1 denominator) for unbiased estimation.

   Args:
       values: 1D array of values.
       mask: Boolean mask (True for valid values).
       mean: Pre-computed mean. If None, computed from masked values.

   Returns:
       Standard deviation of valid values.


.. py:function:: small_sample_penalty(n)

   Compute the Mawet et al. (2014) small-sample statistics correction.

   At small angular separations, fewer reference apertures are available,
   which inflates the noise estimate. This penalty factor accounts for
   the additional uncertainty.

   Reference: Mawet et al. (2014) ApJ
              Equation 9: sigma_corrected = sigma * sqrt(1 + 1/n)

   Args:
       n: Number of reference apertures.

   Returns:
       Correction factor sqrt(1 + 1/n).