NAME:
  ccdsat
 PURPOSE:   (one line only)
  Find saturation properties of a CCD from one or more images
 DESCRIPTION:
  This program will scan one or more CCD images and will save the highest
    count seen at each row.  This will not be particularly interesting for
    just one image but when fed data from one or more nights a curve will
    emerge that shows the saturation level of the device as a function of
    row number.
 CATEGORY:
  CCD data processing
 CALLING SEQUENCE:
  ccdsat,fn
 INPUTS:
  fn - one or more file names to scan, default='' which means to use PATH and
          PATTERN to get the files
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  OUTFILE - Name of output file, default = 'ccdsat.dat'
  PATH - Path of where to find the source images, default=current directory.
  PATTERN - File searching pattern, default='*.fits'
  PEAKS - Array containing previous peak values vs. row number for each
            amplifier.  Default is to start with a fresh array filled with
            zeros.
  FITS - Flag, if set will indicate that the output file should be written
            in FITS format.  The default is to write an ASCII file which
            contains the numbers in tabular format, one amplifier to a column.
  NOPLOT-Flag, if set, the plots will not be generated.
 OUTPUTS:
  A file, name given in OUTFILE, is written with the peak value seen on each
    row for each amplifier.
 KEYWORD OUTPUT PARAMETERS:
  PEAKS - Array containing peak values vs. row number for each amplifier
 COMMON BLOCKS:
  None.
 SIDE EFFECTS:
  Plot window 0 is used to show the results of the peak finding process
    as each image is scanned.  The green curve is the overall peak and the
    red curve is the peak of each individual image.
 RESTRICTIONS:
  The images given to this program should all be the same size and must match
    the size of the PEAKS input array (if provided).  Also, this program won't
    help if the data don't contain truly saturated pixels somewhere in the
    images.
    Any frame whose dimensions do not match the first frame processed will
    be skipped with a diagnostic message.

  This program is still new and is not fully general yet.  It only works
    on multi-group FITS images at this point and the plot window is hardcoded
    to a 4x4 grid of plots that make the most sense for the 16-amp readout
    data from the CTIO Mosaic camera.
 PROCEDURE:
  The simplest usage of this program is to give it one night's worth of data.
    Ex:
      ccdsat,path='/mydata/night1'

  this will look in /mydata/night1 for any file that ends in .fits  You
  will see a plot with each image and the saturation level will begin to
  emerge as each successive image is readout.  If you need to customize the
  file list, you can do so by providing your own array of file names and
  bypassing the automatic scanning.

  If you wish to see an aggregate saturation curve that covers multiple
    nights, use the PEAKS keyword and collect the answer into a variable
    that will be reused for later nights, ie.:

    ccdsat,path='/mydata/night1',peaks=peaks
    ccdsat,path='/mydata/night2',peaks=peaks
    ccdsat,path='/mydata/night3',peaks=peaks        and so on.

  Each run of the program will start where the previous run left off and the
    final run will contain the cumulative answer for all nights.

 MODIFICATION HISTORY:
  Written by Marc W. Buie, Lowell Observatory, 2003/08/30
  2003/09/10, MWB, added PEAKS keyword, additional cleanup of code
  2003/11/13, MWB, added code for simple images (no extensions)
  2004/9/21, MWB, removed obsolete call to Findfile
  2007/12/04, Peter L. Collins, Lowell Observatory, added /NOPLOT and
              test to skip odd sized (sub) frames.