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