PRO pattern_scale_2d, data, inv_var, patt_arr, fsol, fsol_err, model, chisq, status, DanIDL_C_code, CONSTANT = constant
; Description: This module fits a linear combination of a set of two-dimensional patterns,
; stored in the pattern array "patt_arr", to a two-dimensional set of data
; "data" using inverse variance weights "inv_var". Mathematically, the data
; "data" are modelled as:
;
; M(x,y) = f_1*P_1(x,y) + f2*P_2(x,y) + ... + f_N*P_N(x,y)
;
; where M(x,y) is the model for the data D(x,y), P_i(x,y) represents the
; ith pattern, f_i is the ith scale factor, and N is the number of patterns.
; The model can also be adjusted to include an additive constant C by setting
; the keyword CONSTANT. The scale factors (and constant, if requested) are
; returned to the user via the solution vector "fsol" along with their
; uncertainties "fsol_err". The model M(x,y) is also returned as the array
; "model".
; This module will use C++ code if possible to achieve a faster execution
; than the default IDL code. The C++ code can be up to a factor of ~1.5 times
; faster than the IDL code in this case. The C++ code is currently implemented
; only for the model consisting of a scaled pattern and additive constant.
;
; Input Parameters:
;
; data - FLOAT/DOUBLE ARRAY - A two-dimensional array to which the linear combination of
; two-dimensional pattern arrays are to be fitted.
; inv_var - FLOAT/DOUBLE ARRAY - An array of the same size as "data", that contains the
; inverse variance weights to be used when fitting the
; linear combination of pattern arrays. If this array does
; not have the same dimensions as "data", then all the data
; values are weighted equally. In this case, and in the
; case where the weights "inv_var" do not represent the
; inverse variances, the output uncertainties in "fsol_err"
; and the chi squared "chisq" of the fit are meaningless.
; Bad data values may be pre-flagged by setting the
; corresponding values in this array to zero (or negative
; values).
; patt_arr - FLOAT/DOUBLE ARRAY - A three-dimensional array containing the set of
; two-dimensional patterns P_1(x,y), P_2(x,y), ...,
; P_N(x,y) to be fitted as a linear combination to the
; input data "data". The first dimension should be of
; size N. The next two dimensions should have the same
; size as those of the input data "data". To ensure a
; stable solution, none of these patterns should be
; identical, or a scaled version of another pattern.
; DanIDL_C_code - STRING - The full directory path indicating where the DanIDL C++ code is
; installed. The shared library of DanIDL C++ routines should exist
; as "/dist/libDanIDL.so" within the installation.
;
; Output Parameters:
;
; fsol - DOUBLE VECTOR - A vector of scale factors of length N elements representing the
; solutions f_1, f_2, ..., f_N. If the keyword CONSTANT was set,
; then this vector will actually be of length N+1, and the last
; element represents the fitted additive constant C. Scale factors
; are set to "0.0" where the scale factor is unconstrained by the
; input data.
; fsol_err - DOUBLE VECTOR - A vector of the same length as "fsol" with values representing
; the uncertainties on the values stored in "fsol". The values
; in this vector only represent uncertainties in the case where
; the weights "inv_var" are inverse variances. Uncertainties
; are set to "-1.0" where the scale factor is unconstrained by
; the input data.
; model - DOUBLE ARRAY - A two-dimensional array of the same size as "data" representing
; the model M(x,y).
; chisq - DOUBLE - The chi squared of the fit ignoring bad data values flagged in "inv_var".
; This quantity only represents the chi squared in the case where the
; weights "inv_var" are inverse variances.
; status - INTEGER - If the module successfully fit a linear combination of pattern arrays
; to the input data, then "status" is returned with a value of 1,
; otherwise it is returned with a value of 0.
;
; Keywords:
;
; If the keyword CONSTANT is set (as "/CONSTANT"), then the module will include an additive
; constant C in the model such that:
;
; M(x,y) = f_1*P_1(x,y) + f2*P_2(x,y) + ... + f_N*P_N(x,y) + C
;
; The fitted value of C and its uncertainty will be returned as the last elements of the
; vectors "fsol" and "fsol_err" respectively.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 24/04/2009 - Further module optimisation performed (dmb).
; 11/12/2008 - Module created (dmb)
;Check that "data" is a two-dimensional array of the correct number type
;If "inv_var" does not have the same dimensions as "data" or the correct number type, then weight
;all data points equally
;If "inv_var" does have the same dimensions as "data" and the correct number type, then set any
;negative weights equal to zero, checking that not all data points are flagged as bad
;Check that "patt_arr" is a three-dimensional array of the correct number type and size
;Calculate the solution for the simple case where the model consists of a single pattern and no
;additive constant
;Check that the single pattern scale factor is constrained by the data
;Calculate the scale factor solution and its uncertainty
;Construct the model for the input data
;Calculate the chi squared of the fit
;Determine if the shared library of DanIDL C++ routines is installed
;Calculate the solution for the simple case where the model consists of a single pattern and an
;additive constant
;Check that the single pattern scale factor is constrained by the data
;If the single pattern scale factor is not constrained by the data, then calculate the solution
;for the additive constant only
;Calculate the additive constant solution and its uncertainty
;Construct the model for the input data
;Calculate the chi squared of the fit
;If the single pattern scale factor is constrained by the data, then calculate the solutions for
;both the scale factor and the additive constant
;If the shared library of DanIDL C++ routines is installed, then use the C++ code to speed up
;the calculation of the scale factor and additive constant
;Solve for the kernel and differential background solution
;If the shared library of DanIDL C++ routines is not installed, then use the default IDL code
;Calculate the scale factor solution, the additive constant solution, and their uncertainties
;Construct the model for the input data
;Calculate the chi squared of the fit
;Return a status of "1"
;Determine the subset of patterns that are constrained by the data
;Calculate the solution for the general case where the model consists of multiple patterns and
;no additive constant
;If non of the scale factors are constrained by the data, then return with an unsuccessful fit
;Set up some necessary variables
;Set up the relevant least squares matrix and vector on the right hand side
;Pre-calculate a temporary array
;Assign the diagonal matrix element
;Calculate various matrix elements
;Copy across symmetrical elements
;Calculate a vector element
;Calculate the remaining matrix element and vector element
;Compute the inverse of the matrix using LU decomposition
;Solve the system of linear equations
;Construct the model for the input data
;Calculate the chi squared of the fit
;Calculate the solution for the general case where the model consists of multiple patterns and
;an additive constant
;Set up the solution vectors
;If non of the scale factors are constrained by the data, then calculate the solution for the
;additive constant only
;Calculate the additive constant solution and its uncertainty
;Construct the model for the input data
;If at least one of the scale factors is constrained by the data, then calculate the solution
;for the scale factors and the additive constant
;Set up some necessary variables
;Set up the relevant least squares matrix and vector on the right hand side
;Pre-calculate a temporary array
;Calculate various matrix elements
;Copy across symmetrical elements
;Calculate a vector element
;Calculate the remaining four matrix and two vector elements
;Compute the inverse of the matrix using LU decomposition
;Solve the system of linear equations
;Construct the model for the input data
;Calculate the chi squared of the fit