:py:mod:`kai.mtf.mmm`
=====================

.. py:module:: kai.mtf.mmm

.. autoapi-nested-parse::

   
   ..
       !! processed by numpydoc !!


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


Functions
~~~~~~~~~

.. autoapisummary::

   kai.mtf.mmm.mmm



.. py:function:: mmm(sky_vector, highbad=None, readnoise=None, integer=False, debug=False, silent=False)

   
   Estimate the sky background in a stellar contaminated field.

   MMM assumes that contaminated sky pixel values overwhelmingly display 
   POSITIVE departures from the true value.  Adapted from DAOPHOT 
   routine of the same name.

    CALLING SEQUENCE:
          MMM, sky, [ skymod, sigma, skew, HIGHBAD = , READNOISE=, /DEBUG, 
                     NSKY=, /INTEGER,/SILENT]

    INPUTS:
          SKY - Array or Vector containing sky values.  This version of
                  MMM does not require SKY to be sorted beforehand.  SKY
                  is unaltered by this program.

    OPTIONAL OUTPUTS:
          skymod - Scalar giving estimated mode of the sky values
          SIGMA -  Scalar giving standard deviation of the peak in the sky
                  histogram.  If for some reason it is impossible to derive
                  skymod, then SIGMA = -1.0
          SKEW -   Scalar giving skewness of the peak in the sky histogram

                  If no output variables are supplied or if /DEBUG is set
                  then the values of skymod, SIGMA and SKEW will be printed.

    OPTIONAL KEYWORD INPUTS:
          HIGHBAD - scalar value of the (lowest) "bad" pixel level (e.g. cosmic 
                   rays or saturated pixels) If not supplied, then there is 
                   assumed to be no high bad pixels.
          READNOISE - Scalar giving the read noise (or minimum noise for any 
                   pixel).     Normally, MMM determines the (robust) median by 
                   averaging the central 20% of the sky values.     In some cases
                   where the noise is low, and pixel values are quantized a
                   larger fraction may be needed.    By supplying the optional
                   read noise parameter, MMM is better able to adjust the
                   fraction of pixels used to determine the median.                
          /INTEGER - Set this keyword if the  input SKY vector only contains
                   discrete integer values.    This keyword is only needed if the
                   SKY vector is of type float or double precision, but contains 
                   only discrete integer values.     (Prior to July 2004, the
                   equivalent of /INTEGER was set for all data types)
          /DEBUG - If this keyword is set and non-zero, then additional 
                  information is displayed at the terminal.
          /SILENT - If set, then error messages will be suppressed when MMM
                   cannot compute a background.    Sigma will still be set to -1
    OPTIONAL OUTPUT KEYWORD:
         NSKY - Integer scalar giving the number of pixels actually used for the
                sky computation (after outliers have been removed).
    NOTES:
          (1) Program assumes that low "bad" pixels (e.g. bad CCD columns) have
          already been deleted from the SKY vector.
          (2) MMM was updated in June 2004 to better match more recent versions
          of DAOPHOT.
          (3) Does not work well in the limit of low Poisson integer counts
          (4) MMM may fail for strongly skewed distributions.
    METHOD:
          The algorithm used by MMM consists of roughly two parts:
          (1) The average and sigma of the sky pixels is computed.   These values
          are used to eliminate outliers, i.e. values with a low probability
          given a Gaussian with specified average and sigma.   The average
          and sigma are then recomputed and the process repeated up to 20
          iterations:
          (2) The amount of contamination by stars is estimated by comparing the 
          mean and median of the remaining sky pixels.   If the mean is larger
          than the median then the true sky value is estimated by
          3*median - 2*mean

    REVISION HISTORY:
          Adapted from Python to IDL -- J. R. Lu 2010-05-30















   ..
       !! processed by numpydoc !!

