NAME:
   synflat
 PURPOSE:
   Create a synthetic flat frame with optional overscan
 DESCRIPTION:
   Using a base flat field array, a signal level in photons, and a gain,
   a flat image array is created with the flat aberrations and the
   photon (Poisson) statistics.
   We add to this a base dark image and a bias frame that is created by 
   synbias,
   which adds  a bias level (overscan level) and simulated read noise 
   - an optional overscan area is created that contains bias and
   read noise only. The sigma is specified for the read noise, which
   is normally distributed wih a mean of 0. The final output is an
   integer array.
 CATEGORY:
   CCD data processing
 CALLING SEQUENCE:
   synflat,flatbase,slvl,darkbase,etime,gain,biasbase,biaslevel,rdnoise,seed,$
      flatframe
 INPUTS:
   flatbase = 2-D float input array. This is conceptually a constant and
              consists of dimensionless values between 0 and 1.0 that multiply
              the base signal (sky or screen) level of the flat.
   slvl     = flat signal level in counts.
   darkbase = 2-D integer float input array. This is conceptually a constant
              and is multiplied by the exposure time to generate the
              ideal dark image (units are counts per second)
   etime    = exposure time in seconds
   gain       hypothetical gain (e-/DN) for statistics
   biasbase = 2-D input array.  This is conceptually a constant, normally
              floating point, with each pixel in units of D/N (counts).
              It represents the bias structure introduced by the electronics.
   biaslevel  bias (overscan) level, in units of D/N (counts)
   rdnoise    value in electrons/pixel. Sigma for bias is rdnoise/gain.
   seed       for random number generator- both input and output.
   seed       for random number generator- both input and output.
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
   OVERSCAN - integer, number of columns for the explicit overscan area.
              If less than or equal to 0, there is no overscan area generated
              and the dimensions of the output array matches biasbase.
   FITSFN -   Fits file for the flat frame. The exposure time is included
              in the header. The default is to generate no file.
   CRSNUM -   number of cosmic ray strikes per ccd area of image. The units
              are strikes per megapixel per image. Cosmic rays will not be 
              placed in the overscan area, if one is defined. The count
              of CRS for an image is chosen as a Poisson deviate with the
              given mean.
   CRSMIN  -  minimum D/N for cosmic ray strikes that will be added to the 
              output.
   CRSMAX  -  maximum D/N for cosmic ray strikes that will be added to the 
              output. Intensity of each CRS is drawn uniformly over the
              range [CRSMIN,CRSMAX].
   STARRATE - mean number of stars added per image. Stars are gaussian
              PSF's as computed by synstar. Stars will not be placed in the
              overscan area, if one is defined. The number of stars
              for an image is chosen as a Poisson deviate with the
              given mean.
   STARMIN -  minimum flux-  as passed to synstar- for stars that will be 
              added to the output.
   STARMAX -  maximum flux-  as passed to synstar- for stars that will be 
              added to the output. Flux of each star is drawn uniformly 
              over the range [STARMIN,STARMAX].
 KEYWORD OUTPUT PARAMETERS:
   CRSOUT  -  Output, number of cosmic rays added to the image.
   STARSOUT - Output, number of stars added to the image.

 OUTPUTS:
   flatframe - 2-D int array that is the synthetic flat image. Its dimensions
               are n x (m + o) where  n, m are the dimensions of  flatbase and
               o is the number of overscan columns created. The overscan 
               area of the flat is flatframe[n:n+o-1, *]. Pixels are in units
               of D/N counts. Pixel values are  calculated in floating point 
               and rounded to nearest integer. They are truncated at 32767.

 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 Only handles single images- the darkbase, flatbase  and biasbase must be 
 identically dimensioned.
 PROCEDURE:
 MODIFICATION HISTORY:
   2006 June 28, Written by Peter L. Collins, Lowell Observatory  
   2006/07/10    PLC, reorder arguments for consistency
   2006/07/12    PLC, CRS keywords- other documentation and argument cleanups.
   2006/07/12    PLC, add keywords CRSOUT and STARSOUT.
   2006/07/14, MWB, final cleanup and addition to library.