FUNCTION median_with_mask, data, mask, NOSTDDEV = nostddev, NO_PAR_CHECK = no_par_check
; Description: This function calculates the median and standard deviation of a set of data
; values ignoring any masked/bad values.
;
; Input Parameters:
;
; data - FLOAT/DOUBLE ARRAY - A data array of any dimensions containing the set of data
; values for which the median is to be calculated.
; mask - BYTE/INTEGER/LONG ARRAY - An array of the same size and dimensions as "data",
; that contains the mask of good and bad data points.
; Good data points should be flagged with a value of "1",
; and bad data values flagged with any other value,
; although setting bad data values to have mask values of
; "0" is the common practice. If this array does not have
; the same number of elements as "data", then all the
; data values are considered good.
;
; Return value:
;
; The function returns an IDL structure with the following tags:
;
; median - DOUBLE - The median of the good data values.
; stddev - DOUBLE - The standard deviation of the good data values.
; ngood - LONG - The number of good data values used in the calculation of "median".
;
; Keywords:
;
; If the keyword NOSTDDEV is set (as "/NOSTDDEV"), then the function will not include the
; standard deviation with the tag name "stddev" in the IDL structure that is returned. Set
; this keyword if the standard deviation is 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:
;
; 02/05/2008 - Module created (dmb)
;Perform parameter checking if not instructed otherwise
;Check that "data" contains numbers of the correct type, and determine the number of elements
;in "data"
;Check that "mask" contains numbers of the correct type
;If "mask" does not have the same number of elements as "data", then assume that all data points are good
;If "mask" does have the same number of elements as "data", then find the subscripts of the "good" data points
;If there are at least 2 good data points
;Calculate the median and standard deviation of the data array ignoring bad data points
;If there is 1 good data value
;If there are no good data values
;Return the median and number of good pixels used in the calculation. Also return the
;standard deviation if required.