NAME:
   avger
 PURPOSE: (one line)
   Temporal averaging of time-series data.
 DESCRIPTION:
   This program was written to perform N point averaging of raw photometry
   data.  It will work on any temporal data streams or data that has clumpy
   independent variable values.  The data are grouped together into bin
   that are specified by the THRESH input.  Thresh specifies the size of a
   gap that will cause the group to be broken.  The value for thresh is taken
   to be a multiple of the 'normal' spacing between points.  If THRESH=2,
   then any gap twice as long as the previous point spacing will cause a
   break.  Any number equal to or less than 1 will prevent all averaging.
   To prevent too much binning for long uniform data runs, MAXBIN puts an
   upper limit on the number of points that can be grouped together and
   XSPREAD limits the xspan within a single group.

   The THRESH criterion is applied to the data first for grouping,
   then MAXBIN and XSPREAD are used simultaneously to break up long
   binning strings.

   The data are averaged together using a weighted average (see MEANERR).
   The uncertainty returned is the standard deviation of the mean.

 CATEGORY:
   Numerical
 CALLING SEQUENCE:
   pro avger,x,y,err,maxbin,thresh,avgx,avgy,sigy
 INPUTS:
      x      - Independent variable.
      y      - Dependent variable.
      err    - Uncertainty on y in units of standard deviation.
               This can be a scalar or a vector but must not be zero.
      maxbin - Maximum number of points to average together.
      thresh - Gap that will break grouping of data as a fraction of normal.
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
      DATAERR - Output vector of sigma of the mean computed directly
                 from the scatter in the data.  If the number of points
                 in an output bin is one, then the output error is the
                 same as the input error.
      FORCEIT - 2xN vector, First column is a point number and the second
                 column is a flag, 0 means force this point to bin, 1 means
                 force a break at this point.  Point numbers outside of
                 the valid data range are silently ignored.  This info
                 if supplied overrides the breaking controlled by THRESH,
                 MAXBIN, and XSPREAD allowing a direct modification of
                 binning for pathalogical cases.
                    Example:
                       forceit=[[13,0],[14,1],[19,0]]
                    would force points 13 and 19 to NOT end the binning
                    and would force point 14 to be the end of a bin.
                    When using this option, VERBOSE is especially useful.
      XSPREAD - maximum range of x allowed in a single averaged point.
                 (default = no limit).
      VERBOSE - Flag, if true will cause a complete printout of how the
                 vector is being binned.
 OUTPUTS:
      avgx   - X value after binning.
      avgy   - Y value after binning.
      sigy   - New uncertainty.
 KEYWORD OUTPUT PARAMETERS:
      NPTS   - Vector that contains the number of points averaged for each
                 output point.
      GROUP  - Vector that matched the length of the input vector.  The
                 value of the vector gives the group number of each data
                 point.  This is built from NPTS.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
   The input vectors must have equal length and should be greater in length
   than 3.  If the vectors are of length 2 or 3, the program will return a
   straight average of all input values.  Scalar inputs are not allowed and
   will generate an error.
 PROCEDURE:
 MODIFICATION HISTORY:
    1993/05/11 - Written by Marc W. Buie, Lowell Observatory.
    1994/03/21, MWB, modified to output double precision if input is double.
    1994/02/25, MWB, added XSPREAD control over binning.
    1998/01/16, MWB, added DATAERR keyword
    2009/02/12, MWB, fixed error in DATAERR calculation.
    2010/12/13, MWB, added NPTS output keyword
    2012/01/02, MWB, added GROUP output keyword