PRO fit_linear_transform_2d, x1, y1, x2, y2, weights_x, weights_y, param, param_err, det, model_x2, model_y2, chisq, status, ERRBAR = errbar
; Description: This module fits a linear transformation with six free parameters that maps as
; closely as possible (in a least squares sense) the points with coordinates "(x1,y1)"
; in the coordinate space S1 to the same points with coordinates "(x2,y2)" in a
; different coordinate space S2. The fitted model relating the coordinates in S1 to
; the coordinates in S2 is defined by:
;
; x2 = A*x1 + B*y1 + E
; y2 = C*x1 + D*y1 + F
;
; If required, the fit to the "x2" and "y2" coordinates in S2 can be weighted via
; the parameters "weights_x" and "weights_y" for the x and y dimensions, respectively.
; The fitted parameters A, B, C, D, E and F are returned via the output parameter
; "param" along with the status of the fit "status". Note that the set of points
; defined by the input parameters "x1" and "y1" must not be collinear, otherwise
; the linear transformation fit is degenerate and the module will fail.
; In the case that the weights of the fit in each dimension of S2, "weights_x" and
; "weights_y", represent the inverse variance weights for the dependent data "x2" and
; "y2" respectively, then the uncertainties on the fitted parameters are represented
; by "param_err", and the overall chi squared of the fit is represented by "chisq".
; The module also provides the option of treating the weights as representing the
; 1-sigma uncertainties on the coordinates "x2" and "y2", in which case the actual
; weights that are used in the fit are the inverse variance weights, and again the
; uncertainties on the fitted parameters are represented by "param_err", and the
; overall chi squared of the fit is represented by "chisq".
;
; Input Parameters:
;
; x1 - FLOAT/DOUBLE VECTOR/ARRAY - A vector or array of x coordinates for the points in the
; coordinate space S1. This vector/array must have at least
; three elements.
; y1 - FLOAT/DOUBLE VECTOR/ARRAY - A vector or array of y coordinates for the points in the
; coordinate space S1. This vector/array must have the same
; number of elements as "x1".
; x2 - FLOAT/DOUBLE VECTOR/ARRAY - A vector or array of x coordinates for the points in the
; coordinate space S2. This vector/array must have the same
; number of elements as "x1".
; y2 - FLOAT/DOUBLE VECTOR/ARRAY - A vector or array of y coordinates for the points in the
; coordinate space S2. This vector/array must have the same
; number of elements as "x1".
; weights_x - FLOAT/DOUBLE VECTOR/ARRAY - A vector or array with the same number of elements
; as "x1", that contains the weights to be used in
; the calculation of the parameters A, B and E in the
; fitted linear transformation. If this parameter does
; not have the correct number type or the same number
; of elements as "x1", then all values of "x2" are
; weighted equally. Values of "x2" to be ignored can
; be pre-flagged by setting the corresponding weights
; in this vector/array to zero (or negative values).
; If the keyword ERRBAR is set, then the module will
; assume that the values in this parameter represent
; the 1-sigma uncertainties on the "x2" values, and
; it will calculate the actual weights to be used in
; the fit as the inverse variance weights.
; weights_y - FLOAT/DOUBLE VECTOR/ARRAY - A vector or array with the same number of elements
; as "x1", that contains the weights to be used in
; the calculation of the parameters C, D and F in the
; fitted linear transformation. If this parameter does
; not have the correct number type or the same number
; of elements as "x1", then all values of "y2" are
; weighted equally. Values of "y2" to be ignored can
; be pre-flagged by setting the corresponding weights
; in this vector/array to zero (or negative values).
; If the keyword ERRBAR is set, then the module will
; assume that the values in this parameter represent
; the 1-sigma uncertainties on the "y2" values, and
; it will calculate the actual weights to be used in
; the fit as the inverse variance weights.
;
; N.B: This module performs the extra test that the set of points defined by the input parameters
; "x1" and "y1" is not collinear. If this is not the case, then the module will fail, because
; the linear transformation fit is degenerate.
;
; Output Parameters:
;
; param - DOUBLE VECTOR - A vector of six DOUBLES representing the fitted quantities A, B, C,
; D, E and F in this order.
; param_err - DOUBLE VECTOR - A vector of six DOUBLES representing the uncertainties on the
; fitted quantities A, B, C, D, E and F in this order. The values
; in this output parameter are only meaningful if the input weights
; "weights_x" and "weights_y" represent the inverse variances for
; the dependent data "x2" and "y2", respectively, or if the keyword
; ERRBAR is set (see below) and the weights "weights_x" and
; "weights_y" represent the 1-sigma uncertainties on the dependent
; data "x2" and "y2", respectively.
; det - DOUBLE - The determinant of the linear transformation defined by:
;
; det = (A*D) - (B*C)
;
; model_x2 - DOUBLE VECTOR/ARRAY - A vector or array (of the same dimensions as the input
; parameter "x2") of x coordinates in the coordinate space S2
; obtained by transforming the x and y coordinates of the
; points in the coordinate space S1 using the fitted model
; transformation.
; model_y2 - DOUBLE VECTOR/ARRAY - A vector or array (of the same dimensions as the input
; parameter "y2") of y coordinates in the coordinate space S2
; obtained by transforming the x and y coordinates of the
; points in the coordinate space S1 using the fitted model
; transformation.
; chisq - DOUBLE - The chi squared of the fit ignoring bad data values flagged in "weights_x"
; and "weights_y". This quantity only represents the chi squared in the case
; where the input weights "weights_x" and "weights_y" represent the inverse
; variances for the dependent data "x2" and "y2", respectively, or if the
; keyword ERRBAR is set (see below) and the weights "weights_x" and
; "weights_y" represent the 1-sigma uncertainties on the dependent data "x2"
; and "y2", respectively.
; status - INTEGER - If the module successfully fit a linear transformation to the coordinate
; data, then "status" is returned with a value of "1", otherwise it is
; returned with a value of "0".
;
; Keywords:
;
; If the keyword ERRBAR is set (as "/ERRBAR"), then the module will assume that the weights
; "weights_x" and "weights_y" represent the 1-sigma uncertainties on the coordinates "x2" and
; "y2", respectively, and it will calculate the actual weights to be used in the fit as the
; inverse variance weights.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 01/02/2011 - Module expanded and reorganised to include the calculation of the uncertainties
; on the fitted parameters and the calculation of the chi-squared (dmb).
; 02/11/2010 - Swapped the "invert" function for the more stable "la_invert" function (dmb).
; 11/08/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "x1" and "y1" are of the correct number type
;Check that the first coordinate list has at least three points, and that the number of x
;coordinates is equal to the number of y coordinates for this list
;Copy and reform the input data "x1" and "y1"
;Check that the set of points defined by the input parameters "x1" and "y1" is not collinear
;Check that "x2" and "y2" are of the correct number type
;Check that the second coordinate list has the same number of points as the first coordinate
;list
;Copy and reform the input data "x2" and "y2"
;If "weights_x" is not of the correct number type, or it does not have the same number of
;elements as "x1", then weight all values of "x2" equally, otherwise set any negative weights
;equal to zero. Check that there are at least three points with positive weights. Also, if
;the keyword ERRBAR is set, then convert the 1-sigma uncertainties on the "x2" values to
;inverse variances.
;If "weights_y" is not of the correct number type, or it does not have the same number of
;elements as "x1", then weight all values of "y2" equally, otherwise set any negative weights
;equal to zero. Check that there are at least three points with positive weights. Also, if
;the keyword ERRBAR is set, then convert the 1-sigma uncertainties on the "y2" values to
;inverse variances.
;Calculate the first least squares matrix and the corresponding vector on the right
;Invert the first least squares matrix
;Calculate the parameters A, B and E of the linear transformation along with their uncertainties
;Calculate the second least squares matrix and the corresponding vector on the right
;Invert the second least squares matrix
;Calculate the parameters C, D and F of the linear transformation along with their uncertainties
;Construct the output vector of fitted linear transformation parameters
;Calculate the determinant of the fitted linear transformation
;Calculate the coordinates of the points from the first coordinate list after applying
;the fitted linear transformation
;Calculate the chi squared of the fit
;Adjust the dimensions of "model_x2" and "model_y2" to match those of "x2" and "y2" respectively
;Set "status" to "1"