NAME:
  robomean
 PURPOSE: (one line)
  Robust statistical moments of the data.
 DESCRIPTION:
  This routine computes the average, average deviation, standard
  deviation, variance, skew and kurtosis of the input data.  The various
  output quantities are always returned as floating point scalars.
  The statistics are computed with no regard for the dimensionality of
  the input data.

  The statistics are robust in that the data is searched for outliers
  after the moments are computed.  If outliers are found they are
  removed and the statistics are computed again.  This continues until
  either no outliers are found or if the removal of outliers has an
  insignificant effect on the statistics.
 CATEGORY:
  Statistics
 CALLING SEQUENCE:
  robomean,data,thresh,eps,avg,avgdev,stddev,var,skew,kurt,nfinal
 INPUTS:
  data   - Input data to be analyzed.
  thresh - Deviation from the mean to signify an outlier.
  eps    - Smallest significant change in mean in units of std dev.
 OPTIONAL INPUT PARAMETERS:
  None.
 INPUT KEYWORD PARAMETERS:
  BAD    - Array of flags, 0=good, 1=bad.  Any points removed from the sample
              will have this flag set to 1 upon return.  Note that if you
              do not supply this array, you will not get the resulting bad
              flag output even if you supply the keyword.
 OUTPUTS:
  avg    - Sample mean.
  avgdev - Average deviation of the data from the mean.
  stddev - Standard deviation of the data from the mean.
  var    - Variance of the data from the mean.
  skew   - Skewness, third statistical moment.
  kurt   - Kurtosis, fourth statistical moment.
  nfinal - Number of points used in the final result.
  new    - Vector of 'clean' pixels (optional).
 OUTPUT KEYWORD PARAMETERS:
  STDMEAN - Optional return of standard deviation of the mean.
  ERROR   - Flag, if set indicates that all points were removed.  This can
              be caused by a many things but usually is an indication of some
              pathology in the data.  The most common is to have a true
              mean and standard deviation in the data that is very distant
              from an initial approximation so that all data are excluded on
              a pass (usually the first).
 COMMON BLOCKS:
  None.
 SIDE EFFECTS:
  None.
 RESTRICTIONS:
  None.
 PROCEDURE:
  Standard techniques, see section 13.1 in Numerical Recipies.  The
  thresh and eps values are not tremendously important.  Thresh=5.0
  and eps=0.5 appear to work pretty well most of the time.
 MODIFICATION HISTORY:
  Written by Marc W. Buie, Lowell Observatory, 1992 Jan 20.
  Fix - nfinal was not being returned to calling program.
        Doug Loucks, Lowell Observatory, 1992 Oct 22.
  Fix - Sense of test to determine additional refinement was
        not correct for some cases.  Changed logic to parallel
        the C version, since the WHILE statement is now available
        in IDL.
  Mod - Added by Marc Buie: Argument 'new,' allowing the 'clean' pixels
        to be returned to the caller.
  Mod - 2/11/94, DWL, Added keyword STDMEAN to permit return of this
        value to the caller.
  1997/03/23 - MWB, added BAD keyword and operation.  This program's operation
        should not be any different than what it was if you don't supply BAD.
  1998/07/08, MWB, changed so that NaN values are automatically flagged as bad.
  2000/11/2, MWB, cosmetic rewrite.
  2002/01/15, MWB, fixed a subtle case where the data leads to stdev=0.0
               that was causing the program to crash.
  2005/06/21, MWB, added ERROR return flag.
  2009/12/30, MWB, mod from 2002 caused the program to return the wrong
               answer for noiseless input data.  Changed to allow stdev=0.0
               on return but this case avoids almost all of the internal
               processing in this routine.