% @(#)subtrasky.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:18:48 
\se
SECTION./SKY
\es\co
SUBTRACT/SKY					      01-MAR-1991  DB
\oc\su
SUBTRACT/SKY inframe outframe nx,ny
	remove sky by subtraction of histogram-modeled substitute-sky
\us\pu
Purpose:      Compute most probable sky from histogram of sky reference area
              within image. Subtract this sky from input frame.

\up\sy
Syntax:       SUBTRACT/SKY inframe outframe nx,ny flag 
\ys\pa
              inframe   =  name of input image
\ap\pa
              outframe  =  name of result frame
\ap\pa
              nx,ny     =  dimensions (in pixels) of neighbourhood box 
                           (cf. below), default: 1,1
\ap\pa        flag      =  Y or N to indicate whether or not the central 
                           pixel be included in the computation of the 
                           flux in the box. Default: N
\ap\no
Note:         1.) This command may be useful in situations where, as for
                  deconvolutions, a low but non-negative background is
                  required. (Note, however, that the total flux is not
                  strictly conserved.) It can also lead to a dramatic 
                  reduction of the noise in the background. 
\\
              2.) Inframe must have descriptors HISTOGRAM, STATISTIC,
                  WINDOW_FROM, and WINDOW_TO present as set by command
                  STATISTIC/IMAGE. The histogram must be representative of 
                  the sky in the entire image. That is, the histogram must 
                  not be the one of the full frame! Large-scale structures 
                  in the background must have been removed, e.g. using 
                  FIT/FLAT_SKY. The first and the last histogram bin are
                  assumed to be excess bins as defined for STATISTIC/IMAGE. 
                  The bin width should be chosen such as to sample the 
                  distribution of background pixel values reasonably well. 
                  The quality of the results can be very sensitive to the 
                  high cut which may, therefore, have to be refined after 
                  a first trial. 
\\
              3.) The command works as follows (see also Baade, D., Lucy, 
                  L.B.: 1989, Proc. 1st ESO/ST-ECF Data Analysis Workshop, 
                  p. 169): The sky reference histogram is scaled up to 
                  the frame's full area. The bin-wise ratio to the 
                  (internally calculated) frame's actual histogram then 
                  represents the probability that a pixel with a flux
                  within a given bin is due to sky only. For bins with this
                  probability being unity, all pixels with the corresponding
                  signals are zeroed. For other bins, the probability predicts
                  how many pixels owe their signal to the sky only; let this
                  number be NZERO. Rank all pixels belonging to the given
                  histogram bin according to the average flux in their 
                  neighbourhood of (2*nx+1)*(2*ny+1) pixels. Set the first 
                  (lowest) NZERO pixels this sequence to zero. From the rest 
                  subtract the value of all bins between (i.e., excluding)
                  the lower excess bin and the one considered.
\\
              4.) Pixels in the high excess bin will have the expectation
                  value of all non-excess bins subtracted. From pixels
                  in the low excess bin, the lower cutoff value of the
                  histogram will be subtracted. Therefore, these latter
                  pixels will be recognizable by their negative fluxes.
                  If desired, they can be zeroed by means of REPLACE/IMAGE.
\on\sa
See also:     FILTER/FILL, FIT/FLAT_SKY 
\as\exs
Examples:
\ex
              SUBTRACT/SKY back manipulated 2,2 N
\\
              On the basis of descriptors HISTOGRAM, STATISTIC , WINDOW_FROM,
              and WINDOW_TO generated by command:
\\
                    STATISTIC/IMAGE back (plus suitable parameters!)
\\
	      model the sky in frame back.bdf and subtract the model sky from
              the image. Result will be in frame manipulated.bdf. The ranking 
              of pixels is done on the basis of the flux in a neighbourhood 
              of 5x5 pixels but not including the central pixel of this box. 
\xe\sxe