idlastro / Robust Statistics procedures: RESISTANT_MEAN

[Source code]

NAME
RESISTANT_Mean  
PURPOSE
Outlier-resistant determination of the mean and standard deviation. 
EXPLANATION
RESISTANT_Mean trims away outliers using the median and the median 
absolute deviation.    An approximation formula is used to correct for
the truncation caused by trimming away outliers
CALLING SEQUENCE
RESISTANT_Mean, ARRAY, Sigma_CUT, Mean, Sigma_Mean, Num_RejECTED
                     [/DOUBLE, DIMENSION= , GOODVEC =, BADVEC = ]
INPUT ARGUMENT
ARRAY    = Vector or array to average, NaN values will be ignored
Sigma_CUT = Data more than this number of standard deviations from the
        median is ignored. Suggested values: 2.0 and up.
OUTPUT ARGUMENT
Mean  = the mean of the input array, numeric scalar,    If the 
     DIMENSION keyword is set, then MEAN will be an array with one
     less dimension than the input.
OPTIONAL OUTPUTS
Sigma_Mean = the approximate standard deviation of the mean, numeric 
    scalar.  This is the Sigma of the distribution divided by sqrt(N-1)
    where N is the number of unrejected points. The larger
    SIGMA_CUT, the more accurate. It will tend to underestimate the 
    true uncertainty of the mean, and this may become significant for 
    cuts of 2.0 or less. 
um_RejECTED = the number of points trimmed, integer scalar
OPTIONAL INPUT KEYWORDS
/DOUBLE - If set, then all calculations are performed internally 
      in double precision.  
DIMENSION - for a multi-dimensional array, the dimension over which to
      take the mean, starting at 1. If not set, then the scalar mean
      over all elements is used. If this argument is present, the result
      is an array with one less dimension than Array. For example, if 
      the dimensions of Array are N1, N2, N3, and Dimension is 2, then 
      the dimensions of the result are (N1, N3)    
/SILENT - Set to suppress error messages, e.g.if all values in the array
      are NaN
SUMDIM - Obsolete synonym for DIMENSION
OPTIONAL OUTPUT KEYWORD
Badvec -  Indices of trimmed elements of the input vector
Goodvec -  Indices of non-trimmed elements of the input vector
Wused - synonym for Goodvec (for solarsoft compatibility)
EXAMPLE
IDL> a = randomn(seed, 10000)    ;Normal distribution with 10000 pts
IDL> RESISTANT_Mean,a, 3, mean, meansig, num    ;3 Sigma clipping    
IDL> print, mean, meansig,num
The mean should be near 0, and meansig should be near 0.01 ( =
 1/sqrt(10000) ).     
PROCEDURES USED
MEAN() - compute simple mean, in Exelis library
REVISION HISTORY
Written, H. Freudenreich, STX, 1989; Second iteration added 5/91.
Use MEDIAN(/EVEN)    W. Landsman   April 2002
Correct conditional test, higher order truncation correction formula
         R. Arendt/W. Landsman   June 2002
New truncation formula for sigma H. Freudenriech  July 2002
Divide Sigma_mean by Num_good rather than Npts W. Landsman/A. Conley
                   January 2006
Use of double precision S. Bianchi February 2008
More double precision B. Carcich December 2009
Added DIMENSION keyword (from M. Desnoyer) B. Carcich December 2009
Use IDL's MEAN() function instead of AVG() W. Landsman Jan 2012
Use of Dimension keyword yielded transpose of correct value
              W. Landsman  July 2012
Added NaN keyword to MEAN() call N. Crouzet/WL  April 2013
Allow a row/column to be all NaN values N. Crouzet/WL  April 2013
Use of DIMENSION keyword yielded wrong answer for non-square arrays
                D. Cottingham  December 2014
Use Complement arg in Where to generate BADVEC, Rschwartz70@gmail.com, Feb 2020