FUNCTION mean_sigclip, data, weights, sigma, tol, maxiter, NOSUBS = nosubs, NO_PAR_CHECK = no_par_check ; Description: This function calculates a sigma-clipped weighted mean of a set of data ; values. Bad data values may be pre-flagged and are subsequently ignored. ; Iterations of the sigma-clipping continue until the fractional change in ; the sigma-clipped weighted mean is less than "tol", there are no data ; values left to calculate the mean or "maxiter" iterations have been ; completed. ; ; Input Parameters: ; ; data - FLOAT/DOUBLE ARRAY - A data array of any dimensions containing the set of ; data values for which a sigma-clipped weighted mean is ; to be calculated. ; weights - BYTE/INTEGER/LONG/FLOAT/DOUBLE ARRAY - An array of the same size and dimensions as "data", ; that contains the weights to be used in the ; calculation of the mean. If this array does not have ; the same number of elements as "data", then all the ; data values are weighted equally. Bad data values ; may be pre-flagged by setting the corresponding ; weights in this array to zero (or negative values). ; sigma - FLOAT/DOUBLE - This parameter describes the amount of clipping to be ; performed. For example, setting "sigma" to 3.0 will instruct ; the function to perform a 3-sigma clip on the data values. ; If this parameter is not positive, then it will be reset to ; "3.0". ; tol - FLOAT/DOUBLE - This parameter describes the tolerance of the routine. The ; sigma-clipping iterations will stop if the fractional change ; in the sigma-clipped weighted mean between subsequent iterations ; is less than "tol". The recommended value for "tol" is 0.0001 ; (or 0.01%). A negative value for "tol" will be reset to "0.0001". ; maxiter - INTEGER/LONG - The maximum number of iterations to be preformed before ; returning the sigma-clipped weighted mean. The recommended ; value for "maxiter" is 50. A zero or negative value for this ; parameter will be reset to "50". ; ; Return value: ; ; The function returns an IDL structure with the following tags: ; ; mean - DOUBLE - The sigma-clipped weighted mean. ; mean_sig - DOUBLE - The uncertainty on "mean" calculated using only the standard ; deviation of the sigma-clipped data values. ; stddev - DOUBLE - The standard deviation of the sigma-clipped data values. ; stddev_sig - DOUBLE - The uncertainty on "stddev" calculated using only the standard ; deviation of the sigma-clipped data values. ; ngood - LONG - The number of data values used in the calculation of "mean". ; niter - LONG - The number of iterations performed in calculating the sigma-clipped ; weighted mean. ; subs - LONG ARRAY - A vector of subscripts for the array of data values indicating ; which data values were used in the calculation of the sigma-clipped ; weighted mean. ; status - INTEGER - If the sigma-clipped weighted mean was calculated successfully, then ; "status" is set to "1". Otherwise, if the sigma-clipped weighted mean ; was not calculated successfully, then "status" is set to "0". ; ; Keywords: ; ; If the keyword NOSUBS is set (as "/NOSUBS"), then the function will not include the vector ; of subscripts with the tag name "subs" in the IDL structure that is returned. Set this ; keyword if the subscripts are not required in order to obtain a faster execution of this ; function. ; ; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the program will not ; perform parameter checking on the input parameters, reducing program overheads. ; ; Author: Dan Bramich (dan.bramich@hotmail.co.uk) ; ; History: ; ; 24/04/2009 - Further module optimisation performed resulting in a ~1.3% speed increase (dmb). ; 29/04/2008 - Module created (dmb) ;Perform parameter checking if not instructed otherwise ;Check that "data" contains numbers of the correct type ;Check that "weights" contains numbers of the correct type ;Check that "sigma", "tol" and "maxiter" are numbers of the correct type, and reset their ;values if they are out of range. ;If "weights" does not have the same number of elements as "data", then weight all data points equally ;If "weights" does have the same number of elements as "data", then set any negative weights equal ;to zero ;Set up a data mask ;If there are at least 2 good data points ;Calculate the mean and standard deviation of the data array ignoring bad data points ;Calculate the uncertainty on the mean and standard deviation ;Calculate the sigma clipped mean and standard deviation of the data array ;ignoring bad data points ;Update the data mask using the restricted data point range ;If there are at least 2 good data points ;Calculate the mean and standard deviation of the data array ;ignoring bad data points ;Calculate the error on the mean and standard deviation ;Calculate the percentage change in the mean ;If there is only 1 good data point ;If there are no good data points ;Update the number of iterations performed ;If there is only 1 good data point ;If there are no good data points ;Return the sigma clipped mean, the corresponding standard deviation ;and the uncertainties on these values. Also return the number of ;data points used, along with the corresponding subscripts, if required.