PRO calculate_least_squares_vector, patt_arr, weights, data, vector, status
; Description: This module calculates the least squares vector for a general linear least-squares
; problem, which is the problem of fitting a linear combination of a set of patterns to
; a set of data. Mathematically, the data are modelled as:
;
; M[i] = f_1*P_1[i] + f2*P_2[i] + ... + f_N*P_N[i]
;
; where M[i] is the model for the ith data point D[i], P_j represents the jth pattern,
; f_j is the jth scale factor, and N is the number of patterns. The corresponding
; normal equations are represented by the following matrix equation:
;
; A x = v
;
; where A is a square symmetric matrix (the least squares or Hessian matrix), x is the
; vector of scale factors to be determined, and v is a vector. The solution of this
; system is achieved by inverting the matrix A:
;
; x = A^(-1) v
;
; For more details on the theory of the general linear least-squares problem, please
; see Chapter 15.4 of Numerical Recipes 3rd Edition (Press et al. 2007).
; This module calculates the least squares vector v from the set of patterns "patt_arr",
; the set of data weights "weights" and the set of data values "data", and returns the
; vector v via the parameter "vector".
;
; Input Parameters:
;
; patt_arr - FLOAT/DOUBLE VECTOR/ARRAY - An array, with at least two dimensions, containing the
; set of patterns P_1, P_2, ..., P_N to be used to calculate
; the least squares vector. The first dimension of "patt_arr"
; should always be of size N, which is the number of patterns
; to be fitted. The remaining dimensions of "patt_arr" may be
; of any configuration such that each sub-array "patt_arr[j,*]"
; has a total of M elements. Note that since IDL treats an N
; by 1 array as an N-element one-dimensional vector, this
; module accepts such an N-element one-dimensional vector to
; represent the case when M is equal to "1".
; weights - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array of data weights with M elements.
; If this parameter does not have the correct number
; type or M elements, then all the weights are assumed
; to be "1.0".
; data - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array of data values with M elements.
;
; Output Parameters:
;
; vector - DOUBLE VECTOR - A one-dimensional vector of length N elements that represents the least
; squares vector v.
; status - INTEGER - If the module successfully calculated the least squares vector, 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:
;
; 06/04/2011 - Module created (dmb).
;Set the default output parameter values
;Check that "patt_arr" is of the correct number type, and determine the number of patterns
;If "weights" does not have M elements or the correct number type, then assume that all the data weights have
;the value "1.0"
;Check that "data" is of the correct number type and that it has the correct number of elements
;Calculate the least squares vector
;Set "status" to "1"