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.