PRO calculate_fractional_change, x1, x2, fc, status
; Description: For an original set of values "x1" that have been updated to a new set of values "x2", this module
; calculates the fractional changes "fc" in the updated values compared to the original values.
; Analytically, the fractional change "fc" is defined by:
;
; fc = abs((x2 - x1)/x1)
;
; Clearly "fc" is not defined when "x1" is zero. In this case, "fc" is set to "0.0" when "x1" and "x2"
; are both zero, and "fc" is set to "-1.0" when "x1" is zero and "x2" is non-zero.
;
; Input Parameters:
;
; x1 - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A set of original values supplied as a scalar/vector/array.
; x2 - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A set of updated values supplied as a scalar/vector/array with the
; same number of elements as "x1".
;
; Output Parameters:
;
; fc - DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array (of the same dimensions as the input parameter "x1")
; representing the fractional changes in the updated values "x2" compared to
; the original values "x1" (see "Description" above).
; status - INTEGER - If the module successfully calculated the set of fractional changes "fc", then "status"
; is returned with a value of "1", otherwise it is returned with a value of "0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 04/02/2011 - Module created (dmb).
;Set the default output parameter values
;Check that "x1" and "y1" are of the correct number type and that they have the same number of elements
;If "x1" is a scalar
;Set up the output parameter "fc"
;Set "status" to "1"
;The rest of this code deals with the case that "x1" is a vector/array. Firstly, set up the output parameter "fc".
;Determine which elements of "x1" are non-zero elements and calculate the fractional change for these elements
;Determine which elements of "x1" are zero elements for which "x2" also has corresponding zero elements, and set
;the corresponding elements of "fc" to "0.0"
;Set "status" to "1"