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