NAME: 
  mkflat

 PURPOSE: 
  Collect and combine CCD flat frames into a superflat frame

 DESCRIPTION:

  The files are assumed to be named as 'root'NNN where 'root' is the
  root of the file name that you supply and NNN is a three digit number.
  If your file name has an imbedded '.' then add it to the root.

  The specified range of files are all read in from FITS files.  Then each
  image has the overscan mean subtracted (if desired), cropped (as indicated),
  input bias image is subtracted, and then the dark is multipled by each
  image's exposure time and then subtracted.  These images are then
  normalized using the mean of the SCALE region and then averaged weighting
  by the signal-to-noise ratio of each flat image.  The weighted averaging
  is done with AVGCLIP.PRO which does a robust average of the image
  stack so that cosmic rays, stars, and other transient image defects are
  eliminated.  This will do a very good sky flat if enough images are provided
  of different field pointings.

  When done, the resulting flat image is returned to the caller and the image
  is saved to a FITS file with the specified output filename.

 CATEGORY:
  CCD data processing

 CALLING SEQUENCE:
  mkflat,root,outsuf,start,nframes,bias,dark,flat

 INPUTS:
  root    - Root of the file name (you must include . in the name).
  outsuf  - The suffix of the final output file.
  start   - First frame number to read (integer or long).
               Start can also be a vector of explicit frame numbers to load.
               In this case, nframes need not be specified and in fact will
               be ignored.
  nframes - Number of frames to average.
  bias    - Bias frame image name to subtract from each raw flat.
  dark    - Dark frame image name to subtract from each raw flat.

 OPTIONAL INPUT PARAMETERS:

 KEYWORD INPUT PARAMETERS:

   CROP     = region of original image to save, default=no cropping.
                 [x1,x2,y1,y2]

   DDIR    - Path to the raw data, default = ''

   EXCLUDE - Optional vector of image numbers that should be excluded from
                average.  Default is to include all frames.

   EXPKEY = String, FITS keyword to read to get exposure time, default=EXPTIME

   JUSTMEDIAN - Flag, if set will stop processing after the initial median
                  combination of the image cube and this will be the final
                  answer.  This should used only if the intrinsic noise
                  level of the result can never drop below 1 DN.  Particularly
                  useful for a small number of flat images.

   OVERSCAN = column overscan region to use for frame bias level,
                 default=no overscan subtraction.

   RDNOISE  - Read noise of CCD, [DN], default=10

   SCALE - 4 element vector which, if provide, defines the region of the
           array dimensions that are used to scale the mean
           of the arrays before combining (.  If combined in this
           manner, the arrays are combined weighted by the means.
                 [x1,x2,y1,y2]
           These coordinates apply to the pixel locations AFTER cropping.
           The default is to use the center 50% of the image but not any
           bigger than 200x200 subsection at the center.

 OUTPUTS:
  flat - Final robust averaged and normalized flat image.

 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:

 MODIFICATION HISTORY:
  95/03/10 - Initial crude version written, Marc W. Buie, Lowell Observatory
  95/06/04, MWB, added EXCLUDE keyword
  95/06/13, MWB, added SCALE, OVERSCAN, CROP keywords
  99/06/10, MWB, added EXPTIME keyword and added documentation.
  2000/02/03, MWB, rewrite to add support for multigroup FITS files.
  2000/02/28, MWB, added support for frame numbers > 999.
  2001/02/23, MWB, added option to provide input file list.
  2001/04/28, MWB, added DDIR keyword
  2004/05/05, MWB, fixed SCALE keyword default action.  It was not working
                     right at all and the region selected was much too large.
  2006/07/14, MWB, added RDNOISE keyword
  2006/07/27, MWB, added JUSTMEDIAN keyword
  2006/10/23, MWB, fixed output header keyword problem (remove BSCALE/BZERO)