idlastro / DAOPHOT-Type Photometry Procedures: SKY

[Source code]

NAME
SKY
PURPOSE
Determine the sky level in an image 
EXPLANATION
Approximately 10000 uniformly spaced pixels are selected for the
computation.  Adapted from the DAOPHOT routine of the same name.
The sky is computed either by using the procedure mmm.pro (default) 
or by sigma clipping (if /MEANBACK is set) 
CALLING SEQUENCE
SKY, image, [ skymode, skysig ,/SILENT, /MEANBACK, /NAN, CIRCLERAD= ]
  Keywords available  when MEANBACK is not set (passed to mmm.pro): 
            /DEBUG, HIGHBAD=, /INTEGER, MAXITER=. READNOISE=
  Keywords available when /MEANBACK is set: 
            CLIPSIG=, /DOUBLE, CONVERGE_NUM=, MAXITER=, /VERBOSE 
INPUTS
IMAGE - One or two dimensional array
OPTIONAL OUTPUT ARRAYS
SKYMODE - Scalar, giving the mode of the sky pixel values of the 
        array IMAGE, as determined by the procedures MMM or MEANCLIP
SKYSIG -  Scalar, giving standard deviation of sky brightness.   If it
        was not possible to derive a mode then SKYSIG is set to -1
INPUT KEYWORD PARAMETERS
CIRCLERAD - Use this keyword to have SKY only select pixels within
        specified pixel radius of the center of the image.  If 
        CIRCLERAD =1, then the radius is set equal to half the image
        width.   Can only be used with square images.
MEANBACK - if set, then the background is computed using the 3 sigma 
     clipped mean (using meanclip.pro) rather than using the mode 
     computed with mmm.pro.    This keyword is useful for the Poisson 
     count regime or where contamination is known  to be minimal.
NAN - This keyword must be set to  ignore NaN values when computing 
      the sky.
SILENT - If this keyword is supplied and non-zero, then SKY will not
       display the sky value and sigma at the terminal
e _EXTRA facility can is used to pass optional keywords to the programs
     that actually perform the sky computation: either mmm.pro 
     (default) or meanclip.pro (if /MEANBACK) is set.    The following
     keywords are available with the mmm.pro (default) setting 
IGHBAD - 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.
EADNOISE - 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 image only contains
        discrete integer values.    This keyword is only needed if the
        SKY image is of type float or double precision, but contains 
        only discrete integer values.     
the /MEANBACK keyword is set then the following keywords are available
LIPSIG:  Number of sigma at which to clip.  Default=3
MAXITER:  Ceiling on number of clipping iterations.  Default=5
ONVERGE_NUM:  If the proportion of rejected pixels is less
   than this fraction, the iterations stop.  Default=0.02, i.e.,
   iteration stops if fewer than 2% of pixels excluded.
DOUBLE - if set then perform all computations in double precision.
         Otherwise double precision is used only if the input
         data is double
PROCEDURE
A grid of points, not exceeding 10000 in number, is extracted
from the srray.  The mode of these pixel values is determined
by the procedure mmm.pro or meanclip.pro.   In a 2-d array the grid is 
staggered in each row to avoid emphasizing possible bad columns
PROCEDURE CALLS
MEANCLIP, MMM, DIST_CIRCLE
REVISION HISTORY
Written, W. Landsman   STX Co.            September, 1987     
Changed INDGEN to LINDGEN                 January, 1994
Fixed display of # of points used         March, 1994
Stagger beginning pixel in each row, added NSKY, READNOISE, HIGHBAD
   W. Landsman        June 2004
djustments for unbiased sampling  W. Landsman June 2004
dded /NAN keyword, put back CIRCLERAD keyword W. Landsman July 2004
dded MEANBACK keyword, _EXTRA kewyord ,preserve data type in 
      calculations       W. Landsman November 2005
ix problem for very large images by requiring at least 2 pixels to
be sampled per row.    March 2007    W. Landsman
void possible out of bounds if /NAN set   W. Landsman   Jan 2008
se  TOTAL(/INTEGER)      June 2009
ix occasional out of bounds problem when /NAN set W. Landsman Jul 2013
se HIGHBAD in selecting data points  W. Landsman  Nov 2016