PRO fit_photometric_calibration, instr_mag, weights, star_id, std_star_id, std_star_mag, std_star_colour, airmass, xc, yc, q1, q2, q3, q4, patt_arr, $
; Description: This module fits a photometric model (see below), defined by the parameter "fit_options", to a
; set of input instrumental magnitude measurements "instr_mag". If required, the fit can be weighted
; via the parameter "weights". The fitted parameters of the photometric model are returned via the
; parameter "fit_params" along with the status of the fit "status".
; In the case that the weights of the fit "weights" represent the inverse variance weights for
; the instrumental magnitude measurements "instr_mag", then the uncertainties on the fitted
; parameters that are reported in the parameter "fit_params" are valid uncertainties, and the 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 instrumental magnitude measurements "instr_mag", 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 that are reported in the parameter "fit_params" are valid uncertainties, and
; the chi squared of the fit is represented by "chisq".
; Where possible, this module takes advantage of the special structure of the least squares matrix
; in this fitting problem, which contains a diagonal sub-matrix for those parameters that correspond
; to the magnitudes of the stars without known standard magnitudes. This allows the module to solve
; for the parameters of a photometric model which includes the unknown magnitudes of millions of
; stars without requiring unfeasible amounts of memory or computing power. Specifically the module
; employs the DanIDL module "solve_square_linear_system_with_diagonal_submatrix.pro" where
; appropriate. See the paper by Bramich & Freudling (???, ???, ????) for more details.
; For further flexibility, the module provides the option of iterating the fitting process. By
; setting the keyword ITERATION_PAR to an IDL structure that contains the six tags "method",
; "sigma", "maxrej", "permanent", "tol", and "maxiter" defined below (see under "Keywords"), the
; module will do the following.
; If "sigma" is positive, then the sigma-clip threshold S is taken to be the value of "sigma".
; If "sigma" is negative or zero, then the sigma-clip threshold S is calculated as sqrt(ln(Ngood)),
; where Ngood is the number of instrumental magnitude measurements in "instr_mag" with positive
; weights. This expression for the sigma-clip threshold S may be derived from considerations of the
; Bayesian information criterion.
; If the tag "method" is set to "abs_resid", then, during each iteration of the fitting process,
; all instrumental magnitude measurements with absolute residuals greater than S times the standard
; deviation of the residuals are flagged as candidate outliers. If the tag "method" is set to
; "norm_abs_resid", then, during each iteration of the fitting process, all instrumental magnitude
; measurements with normalised absolute residuals greater than S, where the normalising factors are
; the square roots of the corresponding weights, are flagged as candidate outliers.
; If the tag "maxrej" is set to an INTEGER/LONG type positive number, then this number is
; considered to be the maximum number of instrumental magnitude measurements that can be rejected
; in any one iteration, and consequently, only this number of candidate outliers with the largest
; residuals are rejected. If the tag "maxrej" is set to a FLOAT/DOUBLE type positive number that
; is less than or equal to "1.0", then this number is considered to be the maximum fraction of
; instrumental magnitude measurements that can be rejected in any one iteration, and consequently,
; only the corresponding number of candidate outliers with the largest residuals are rejected. If
; the tag "maxrej" is set to anything else, then there is no limit on the number of instrumental
; magnitude measurements that can be rejected in any one iteration.
; If the tag "permanent" is set to "1", then instrumental magnitude measurements that are
; rejected will remain rejected for all subsequent iterations, meaning that the set of instrumental
; magnitude measurements used at each iteration will only diminish. If the tag "permanent" is set
; to any other value, then instrumental magnitude measurements will not be permanently rejected so
; that if an instrumental magnitude measurement is initially rejected, then it may be subsequently
; included in the fitting process during the later iterations. This protects against non-outlier
; instrumental magnitude measurements being permanently excluded from the calculation of the fit
; parameters when real outliers skew the parameter estimates during the early iterations.
; The iterations stop when the maximum fractional change in the fit parameters is less than or
; equal to "tol", or when there are not enough good instrumental magnitude measurements to be used
; in the fit. To protect against the possibility of the fitting process not converging (or entering
; into an oscillatory regime), a limit of "maxiter" iterations is placed on the number of iterations
; that are performed.
; Useful extra information about the fitting process is returned via the keyword EXTRA_INFO, and
; the subscripts of the instrumental magnitude measurements that were used in the (final iteration
; of the) fit are returned via the keyword DATA_USED_SUBS.
; 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.05 times faster than the IDL code in this case.
;
; Photometric Model:
;
; We use the following notation in the description of the general photometric model:
;
; m_i - The ith instrumental magnitude measurement (see "instr_mag").
; M_k - The (standard) magnitude (known for a standard star or to be determined for a non-standard star) for
; the star k corresponding to the measurement m_i (see "std_star_mag").
; (M - M')_k - The standard colour (for a standard star) for the star k corresponding to the measurement m_i.
; Note that the fiducial colour in the photometric model is assumed to be "0" (see "std_star_colour").
; Z_i - The photometric zero-point corresponding to m_i. Note that the photometric zero-point is the magnitude
; difference between the instrumental and standard magnitudes when all other contributions are zero
; (i.e: when all other independent variables are at their fiducial value). Our implementation of the
; photometric model allows for multiple photometric zero-points to be fit corresponding to multiple
; mutually-exclusive groups of instrumental magnitude measurements (see "group_id_zp").
; D_a - The degree of the polynomial in airmass employed in the photometric model.
; k_mi - The polynomial extinction coefficients (indexed by 1 <= m <= D_a) corresponding to m_i. Our
; implementation of the photometric model allows for multiple linear extinction coefficients to be fit
; corresponding to multiple mutually-exclusive groups of instrumental magnitude measurements (see
; "group_id_ext").
; X_i - The airmass corresponding to m_i (see "airmass").
; X_0 - The fiducial airmass, usually assumed to be "0" implying that the photometric zero-point corresponds
; to the top of the atmosphere (i.e. the photometric zero-point is that of the telescope/camera/detector
; system), although in some cases it is useful to assume a fiducial airmass of "1".
; D_c - The degree of the polynomial in colour employed in the photometric model.
; a_m - The polynomial colour-term coefficients (indexed by 1 <= m <= D_c).
; b - The airmass-colour cross-term coefficient.
; D_xy - The degree of the two-dimensional polynomial of the detector x and y coordinates employed in the
; photometric model.
; c_mn - The polynomial coordinate-term coefficients (indexed by 1 <= m + n <= D_xy).
; x_i - The detector x coordinate corresponding to m_i (see "xc").
; x_0 - The fiducial detector x coordinate, usually chosen to be somewhere near the centre of the detector,
; since the photometric zero-point corresponds to the fiducial x and y coordinates.
; y_i - The detector y coordinate corresponding to m_i (see "yc").
; y_0 - The fiducial detector y coordinate, usually chosen to be somewhere near the centre of the detector,
; since the photometric zero-point corresponds to the fiducial x and y coordinates.
; D_q - The degree of the one-dimensional polynomial of the first general "quantity" employed in the
; photometric model.
; d_m - The polynomial "quantity"-term coefficients (indexed by 1 <= m <= D_q) for the first general
; "quantity" employed in the photometric model.
; q_i - The value of the first general "quantity" corresponding to m_i (see "q1").
; q_0 - The fiducial value for the first general "quantity", usually chosen such that the photometric
; zero-point is meaningful when this "quantity" is at the fiducial value.
; D_r - The degree of the one-dimensional polynomial of the second general "quantity" employed in the
; photometric model.
; e_m - The polynomial "quantity"-term coefficients (indexed by 1 <= m <= D_r) for the second general
; "quantity" employed in the photometric model.
; r_i - The value of the second general "quantity" corresponding to m_i (see "q2").
; r_0 - The fiducial value for the second general "quantity", usually chosen such that the photometric
; zero-point is meaningful when this "quantity" is at the fiducial value.
; D_uv - The degree of the two-dimensional polynomial of the third and fourth general "quantities" employed
; in the photometric model.
; f_mn - The polynomial "quantity"-term coefficients (indexed by 1 <= m + n <= D_uv) for the third and
; fourth general "quantities" employed in the photometric model.
; u_i - The value of the third general "quantity" corresponding to m_i (see "q3").
; u_0 - The fiducial value for the third general "quantity", usually chosen such that the photometric
; zero-point is meaningful when both this "quantity" and the fourth general "quantity" are at their
; fiducial values.
; v_i - The value of the fourth general "quantity" corresponding to m_i (see "q4").
; v_0 - The fiducial value for the fourth general "quantity", usually chosen such that the photometric
; zero-point is meaningful when both this "quantity" and the third general "quantity" are at their
; fiducial values.
; N_p - The number of patterns employed in the photometric model.
; g_m - The coefficient of the mth pattern in the photometric model.
; p_mi - The value of the mth pattern corresponding to m_i (see "patt_arr").
;
; We adopt the following general photometric model for each instrumental magnitude measurement:
;
; [ D_a ] [ D_c ]
; m_i = M_k + Z_i + [ SUM k_mi*(X_i - X_0)^m ] + [ SUM a_m*((M - M')_k)^m ] + b*(X_i - X_0)*((M - M')_k)
; [ m=1 ] [ m=1 ]
;
; [ ] [ D_q ]
; + [ SUM c_mn*((x_i - x_0)^m)*((y_i - y_0)^n) ] + [ SUM d_m*(q_i - q_0)^m ]
; [ 1 <= m+n <= D_xy ] [ m=1 ]
;
; [ D_r ] [ ] [ N_p ]
; + [ SUM e_m*(r_i - r_0)^m ] + [ SUM f_mn*((u_i - u_0)^m)*((v_i - v_0)^n) ] + [ SUM g_m*p_mi ]
; [ m=1 ] [ 1 <= m+n <= D_uv ] [ m=1 ]
;
; The exact configuration of the photometric model to be used to fit the instrumental magnitude measurements
; is controlled by the tags in the input parameter "fit_options". Stars may be classed as standard stars, in
; which case their standard magnitudes M_k are fixed, or stars may be classed as non-standard stars, in which
; case their magnitudes M_k are free parameters. Multiple photometric zero-points Z_i and multiple linear
; extinction coefficients k_1i may be fit for separate mutually-exclusive groups of instrumental magnitude
; measurements, providing a flexibility in the model that may account for expected changes in these parameters
; (e.g: separate photometric zero-points for each detector in a camera, separate linear extinction coefficients
; for each night of observation, etc.). Furthermore, all terms in the photometric model are optional, and,
; where appropriate, the polynomial degrees may be specified by the user, leading to a fully configurable and
; flexible photometric model.
; The purpose of the first, second, third, and fourth general quantities is to provide the user with extra
; flexibility in the configuration of the photometric model. These quantities can represent a measure of any
; property associated with each instrumental magnitude measurement that may have influenced the photometry
; (e.g. PSF FWHM, sky background level, time varying instrumental throughput, derotated detector coordinates,
; etc.). This is in fact true of any of the terms in the photometric model, so that, for example, the polynomial
; term corresponding to the detector coordinates could instead be assumed to represent a two-dimensional
; polynomial in right ascension and declination.
; The last term in the photometric model allowing the user to supply N_p patterns enables the module to fit
; any linear photometric model to the instrumental magnitude measurements. Hence, if the standard terms in the
; photometric model that are available in this module do not provide sufficient flexibility, then the user may
; directly supply the required extra patterns to be fit via this last term. For example, the user may wish to
; fit a set of zero-points corresponding to overlapping (rather than mutually-exclusive) groups of instrumental
; magnitude measurements, which is not possible using the standard photometric zero-point terms built into the
; photometric model.
; In general, care must be taken to avoid a degenerate linear regression problem. For example, for models
; with a single photometric zero-point as a free parameter, the regression problem is degenerate if all input
; observations are for non-standard stars only. The degeneracy in this case can be solved by introducing
; measurements of at least one standard star. Note that the module does not check that the linear regression
; problem is degenerate BEFORE attempting to fit the photometric model, although this situation will (usually)
; be detected and reported AFTER attempting the fit.
; There is a very subtle degeneracy that can be introduced when fitting a static illumination correction as a
; function of detector coordinates "xc" and "yc" at the same time as fitting a rotating illumination correction
; as a function of rotated detector coordinates "q3" and "q4". It may be necessary to fit this sort of photometric
; model if elements in the optical path have different rotations relative to the detector for different subsets of
; data. The degeneracy occurs because of the following relation that holds in this specific case:
;
; (xc)^2 + (yc)^2 = (q3)^2 + (q4)^2
;
; This degeneracy can be avoided by removing the polynomial terms of the form (q3)^N, where N is a positive even
; number, from the photometric model. This module provides the option of removing the relevant terms if required
; via the use of the keyword XCYC_Q3Q4_DEGENERACY.
;
; Input Parameters:
;
; instr_mag - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of instrumental magnitudes containing all the individual
; magnitude measurements of all stars that are to be fitted. This
; parameter must have at least two elements.
; weights - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array with the same number of elements as "instr_mag", that
; contains the weights to be used in the calculation of the fitted photometric
; model. If this parameter does not have the correct number type or the same
; number of elements as "instr_mag", then all instrumental magnitude
; measurements are weighted equally. Instrumental magnitude measurements 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 instrumental magnitude measurements, and it
; will calculate the actual weights to be used in the fit as the inverse
; variance weights.
; star_id - STRING VECTOR/ARRAY - A vector/array of strings with the same number of elements as "instr_mag" where
; each element specifies the name of the star to which the corresponding instrumental
; magnitude measurement in "instr_mag" belongs. Note that the module will
; automatically remove any white spaces from the star names.
; std_star_id - STRING SCALAR/VECTOR/ARRAY - The set of star names of the standard stars. Note that the module will
; automatically remove any white spaces from the standard star names.
; The star names in this parameter must each be unique, and this
; parameter must have at least one element that is also present in the
; input parameter "star_id" in order to set the magnitude scale (even if
; the corresponding standard magnitude stored in the parameter
; "std_star_mag" is an arbitrary value).
; std_star_mag - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - The set of standard star magnitudes corresponding to the set
; of standard stars "std_star_id". This parameter must have the
; same number of elements as "std_star_id".
; std_star_colour - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - The set of standard star colours corresponding to the set
; of standard stars "std_star_id". This parameter must have
; the same number of elements as "std_star_id". If the
; photometric model that is to be fitted to the data is
; independent of colour, then this parameter is ignored.
; airmass - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of airmasses with the same number of elements as "instr_mag"
; where each element specifies the fiducially-corrected airmass of the
; corresponding magnitude measurement in "instr_mag". The fiducial airmass
; is usually assumed to be "0", corresponding to the top of the atmosphere,
; or "1", corresponding to the base of the atmosphere and observing to zenith.
; If the photometric model that is to be fitted to the data is independent of
; airmass, then this parameter is ignored.
; xc - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of x pixel coordinates with the same number of elements as
; "instr_mag" where each element specifies the fiducially-corrected detector x
; pixel coordinate of the corresponding magnitude measurement in "instr_mag". The
; fiducial detector coordinates (x0,y0) are usually chosen to be somewhere near the
; centre of the detector since the photometric zero-point corresponds to the fiducial
; coordinates. If the photometric model that is to be fitted to the data is independent
; of detector position, then this parameter is ignored.
; yc - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of y pixel coordinates with the same number of elements as
; "instr_mag" where each element specifies the fiducially-corrected detector y
; pixel coordinate of the corresponding magnitude measurement in "instr_mag". The
; fiducial detector coordinates (x0,y0) are usually chosen to be somewhere near the
; centre of the detector since the photometric zero-point corresponds to the fiducial
; coordinates. If the photometric model that is to be fitted to the data is independent
; of detector position, then this parameter is ignored.
; q1 - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of quantities with the same number of elements as "instr_mag" where
; each element specifies the value of the fiducially-corrected first general quantity
; for the corresponding magnitude measurement in "instr_mag". This quantity may
; represent anything from PSF FWHM to sky background level that the user suspects may
; be correlated with the instrumental magnitude measurements. The fiducial value for
; this quantity is usually chosen such that the photometric zero-point is meaningful
; when the quantity is at the fiducial value. If the photometric model that is to be
; fitted to the data is independent of this quantity, then this parameter is ignored.
; Note that the photometric model employs a one-dimensional polynomial in this quantity.
; q2 - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of quantities with the same number of elements as "instr_mag" where
; each element specifies the value of the fiducially-corrected second general quantity
; for the corresponding magnitude measurement in "instr_mag". This quantity may
; represent anything from PSF FWHM to sky background level that the user suspects may
; be correlated with the instrumental magnitude measurements. The fiducial value for
; this quantity is usually chosen such that the photometric zero-point is meaningful
; when the quantity is at the fiducial value. If the photometric model that is to be
; fitted to the data is independent of this quantity, then this parameter is ignored.
; Note that the photometric model employs a one-dimensional polynomial in this quantity.
; q3 - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of quantities (different to "q4" below) with the same number of
; elements as "instr_mag" where each element specifies the value of the
; fiducially-corrected third general quantity for the corresponding magnitude
; measurement in "instr_mag". This quantity may represent anything from PSF FWHM to
; sky background level that the user suspects may be correlated with the instrumental
; magnitude measurements. The fiducial value for this quantity is usually chosen such
; that the photometric zero-point is meaningful when both this quantity and the fourth
; general quantity are at their fiducial values. If the photometric model that is to
; be fitted to the data is independent of this quantity, then this parameter is ignored.
; Note that the photometric model employs a two-dimensional polynomial in the quantities
; "q3" and "q4".
; q4 - FLOAT/DOUBLE VECTOR/ARRAY - A vector/array of quantities (different to "q3" above) with the same number of
; elements as "instr_mag" where each element specifies the value of the
; fiducially-corrected fourth general quantity for the corresponding magnitude
; measurement in "instr_mag". This quantity may represent anything from PSF FWHM to
; sky background level that the user suspects may be correlated with the instrumental
; magnitude measurements. The fiducial value for this quantity is usually chosen such
; that the photometric zero-point is meaningful when both this quantity and the third
; general quantity are at their fiducial values. If the photometric model that is to
; be fitted to the data is independent of this quantity, then this parameter is ignored.
; Note that the photometric model employs a two-dimensional polynomial in the quantities
; "q3" and "q4".
; patt_arr - FLOAT/DOUBLE ARRAY - An array with at least two dimensions containing the set of patterns p_1, p_2, ..., p_N
; to be fitted as a linear combination to the instrumental magnitude measurements
; "instr_mag". The first dimension 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 with the condition that each sub-array "patt_arr[j,*]" (or pattern)
; contains the same number of elements as "instr_mag". To ensure a stable solution, none
; of the patterns in "patt_arr" should be identical, or a linear combination of any other
; set of patterns. The module will fail if any one pattern consists solely of zeros for
; the instrumental magnitude measurements with positive weights.
; group_id_zp - STRING VECTOR/ARRAY - A vector/array of strings with the same number of elements as "instr_mag" where
; each element specifies the name of an image/measurement grouping to which the
; corresponding magnitude measurement in "instr_mag" belongs and for which an
; individual photometric zero-point is required in the photometric model. Empty
; strings in this vector/array will be interpreted as indicating that the
; corresponding magnitude measurements in "instr_mag" do not belong to any grouping
; for which an individual photometric zero-point is required in the photometric model.
; Instrumental magnitude measurements may therefore be grouped according to individual
; image frames, various sets of image frames, nights of observation, or runs of
; observation (or any other physically meaningful combination). Note that the module
; will automatically remove any white spaces from the group names. At least one string
; in this vector/array must be non-empty. If the photometric model that is to be fitted
; to the data does not allow individual photometric zero-points for different
; image/measurement groups, then this parameter is ignored.
; group_id_ext - STRING VECTOR/ARRAY - A vector/array of strings with the same number of elements as "instr_mag" where
; each element specifies the name of an image/measurement grouping to which the
; corresponding magnitude measurement in "instr_mag" belongs and for which an
; individual linear extinction coefficient is required in the photometric model.
; Instrumental magnitude measurements may therefore be grouped according to
; individual image frames, various sets of image frames, nights of observation,
; or runs of observation (or any other physically meaningful combination). Note
; that the module will automatically remove any white spaces from the group names.
; If the photometric model that is to be fitted to the data does not allow
; individual linear extinction coefficients for different image/measurement groups,
; then this parameter is ignored.
; fit_options - IDL STRUCTURE - A (single) IDL structure containing tags specifying the photometric model to be fit to
; the instrumental magnitude measurements. All of the tags specified below are required to
; be present in "fit_options" in order to fully define the photometric model:
;
; (i) fit_zp - STRING - This tag specifies the type of photometric zero-point to be fitted. The acceptable values are:
;
; no - The module will not fit a photometric zero-point.
; single - The module will fit a single photometric zero-point for all data.
; group - The module will fit a photometric zero-point for each image/measurement grouping
; specified by the input parameter "group_id_zp".
;
; (ii) fit_ext - STRING - This tag specifies the type of linear extinction coefficient to be fitted. The acceptable
; values are:
;
; no - The module will not fit a linear extinction coefficient.
; single - The module will fit a single linear extinction coefficient for all data.
; group - The module will fit a linear extinction coefficient for each image/measurement
; grouping specified by the input parameter "group_id_ext".
;
; (iii) fit_nonlin_ext - INTEGER/LONG - This tag specifies the polynomial degree of the dependence on airmass in the
; photometric model. If the value of this tag is less than or equal to "1", then
; no terms are added to the photometric model.
;
; (iv) fit_col - INTEGER/LONG - This tag specifies the polynomial degree of the dependence on colour in the photometric
; model. If the value of this tag is positive, then the photometric model has a colour
; dependence, and therefore all instrumental magnitude measurements must be of standard
; stars, which have well defined standard colours stored in the parameter "std_star_colour".
; If the value of this tag is zero or negative, then no terms are added to the photometric
; model.
;
; (v) fit_air_col - STRING - This tag specifies if the airmass-colour cross-term coefficient is to be fitted. The
; acceptable values are:
;
; no - The module will not fit an airmass-colour cross-term coefficient.
; yes - The module will fit an airmass-colour cross-term coefficient. In this case, the
; photometric model has a colour dependence, and therefore all instrumental magnitude
; measurements must be of standard stars, which have well defined standard colours
; stored in the parameter "std_star_colour".
;
; (vi) fit_illcorr - INTEGER/LONG - This tag specifies the degree of the two-dimensional polynomial of the detector
; spatial coordinates x and y in the photometric model. If the value of this tag
; is zero or negative, then no terms are added to the photometric model.
;
; (vii) fit_q1 - INTEGER/LONG - This tag specifies the degree of the one-dimensional polynomial of the first general
; quantity "q1" in the photometric model. If the value of this tag is zero or negative,
; then no terms are added to the photometric model.
;
; (viii) fit_q2 - INTEGER/LONG - This tag specifies the degree of the one-dimensional polynomial of the second general
; quantity "q2" in the photometric model. If the value of this tag is zero or negative,
; then no terms are added to the photometric model.
;
; (ix) fit_q3q4 - INTEGER/LONG - This tag specifies the degree of the two-dimensional polynomial of the third and
; fourth general quantities "q3" and "q4" in the photometric model. If the value of
; this tag is zero or negative, then no terms are added to the photometric model.
;
; (x) fit_patt - STRING - This tag specifies if the set of patterns "patt_arr" are to be fitted. The acceptable values
; are:
;
; no - The module will not fit the set of patterns "patt_arr".
; yes - The module will fit the set of patterns "patt_arr".
;
; danidl_cppcode - 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:
;
; fit_params - IDL STRUCTURE - An IDL structure containing the fitted parameters of the photometric model. This
; structure may have any of the following tags:
;
; (i) npar - LONG - The total number of fitted parameters in the photometric model. This tag is always present in
; "fit_params".
;
; (ii) nstars - LONG - The number of stars for which instrumental magnitude measurements were supplied.
;
; (iii) nstars_without_stdmag - LONG - The number of stars for which instrumental magnitude measurements were
; supplied, but for which no standard magnitude was found. In other words, this
; tag specifies the number of non-standard stars for which instrumental magnitude
; measurements were supplied.
;
; (iv) nonstd_star_id - STRING VECTOR - A one-dimensional vector of strings of length "nstars_without_stdmag"
; containing the star names for the non-standard stars. The elements in this
; output parameter are sorted into "ascending" order. This tag is only present
; in "fit_params" if the number of non-standard stars "nstars_without_stdmag" is
; greater than zero.
;
; (v) nonstd_star_mag - DOUBLE VECTOR - A one-dimensional vector of length "nstars_without_stdmag" specifying the fitted
; magnitudes of the non-standard stars. This tag is only present in "fit_params"
; if the number of non-standard stars "nstars_without_stdmag" is greater than zero.
;
; (vi) nonstd_star_mag_err - DOUBLE VECTOR - A one-dimensional vector of length "nstars_without_stdmag" specifying the
; uncertainties in the fitted magnitudes of the non-standard stars. This tag
; is only present in "fit_params" if the number of non-standard stars
; "nstars_without_stdmag" is greater than zero. Note that for photometric
; calibration models where many non-standard star magnitudes are to be
; determined, it may be unfeasible to calculate the covariance matrix (which
; is the inverse of the least squares matrix). Hence, by default, this module
; will not calculate the uncertainties in the fitted magnitudes of the
; non-standard stars when there are at least two magnitudes to be fit, and at
; least one other parameter to be fit. In this case, each value in the output
; parameter "nonstd_star_mag_err" is set to the non-sensical value of "-1.0D".
; The user may force the module to calculate the uncertainties in the fitted
; magnitudes of the non-standard stars in all cases by setting the keyword
; FORCE_CALC_NONSTD_STAR_MAG_ERR.
;
; (vii) zp - DOUBLE - The fitted single photometric zero-point. This tag is only present in "fit_params" if the tag
; "fit_zp" in the input parameter "fit_options" is set to "single".
;
; (viii) zp_err - DOUBLE - The uncertainty in the fitted single photometric zero-point. This tag is only present in
; "fit_params" if the tag "fit_zp" in the input parameter "fit_options" is set to "single".
;
; (ix) ngroups_zp - LONG - The number of image/measurement groupings for which an individual photometric zero-point
; is required in the photometric model. This tag is only present in "fit_params" if the tag
; "fit_zp" in the input parameter "fit_options" is set to "group".
;
; (x) group_zp_ids - STRING VECTOR - A one-dimensional vector of strings of length "ngroups_zp" containing the names of
; the photometric zero-point groupings. The elements in this output parameter are
; sorted into "ascending" order. This tag is only present in "fit_params" if the
; tag "fit_zp" in the input parameter "fit_options" is set to "group".
;
; (xi) group_zp - DOUBLE VECTOR - A one-dimensional vector of length "ngroups_zp" specifying the fitted photometric
; zero-point for each zero-point grouping. This tag is only present in "fit_params" if
; the tag "fit_zp" in the input parameter "fit_options" is set to "group".
;
; (xii) group_zp_err - DOUBLE VECTOR - A one-dimensional vector of length "ngroups_zp" specifying the uncertainty in
; the fitted photometric zero-point for each zero-point grouping. This tag is
; only present in "fit_params" if the tag "fit_zp" in the input parameter
; "fit_options" is set to "group".
;
; (xiii) k - DOUBLE - The fitted single linear extinction coefficient. This tag is only present in "fit_params" if the
; tag "fit_ext" in the input parameter "fit_options" is set to "single".
;
; (xiv) k_err - DOUBLE - The uncertainty in the fitted single linear extinction coefficient. This tag is only present
; in "fit_params" if the tag "fit_ext" in the input parameter "fit_options" is set to "single".
;
; (xv) ngroups_k - LONG - The number of image/measurement groupings for which an individual linear extinction
; coefficient is required in the photometric model. This tag is only present in "fit_params" if
; the tag "fit_ext" in the input parameter "fit_options" is set to "group".
;
; (xvi) group_k_ids - STRING VECTOR - A one-dimensional vector of strings of length "ngroups_k" containing the names of
; the linear extinction coefficient groupings. The elements in this output parameter
; are sorted into "ascending" order. This tag is only present in "fit_params" if the
; tag "fit_ext" in the input parameter "fit_options" is set to "group".
;
; (xvii) group_k - DOUBLE VECTOR - A one-dimensional vector of length "ngroups_k" specifying the fitted linear extinction
; coefficient for each linear extinction coefficient grouping. This tag is only present
; in "fit_params" if the tag "fit_ext" in the input parameter "fit_options" is set to
; "group".
;
; (xviii) group_k_err - DOUBLE VECTOR - A one-dimensional vector of length "ngroups_k" specifying the uncertainty in
; the fitted linear extinction coefficient for each linear extinction coefficient
; grouping. This tag is only present in "fit_params" if the tag "fit_ext" in the
; input parameter "fit_options" is set to "group".
;
; (xix) nonlin_k_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_nonlin_ext - 1" specifying
; the fitted polynomial coefficients for the dependence on airmass in the
; photometric model. The coefficients are ordered in ascending order of degree
; starting with the quadratic coefficient. This tag is only present in
; "fit_params" if the tag "fit_nonlin_ext" in the input parameter "fit_options"
; has a value that is greater than or equal to "2".
;
; (xx) nonlin_k_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_nonlin_ext - 1"
; specifying the uncertainties in the fitted polynomial coefficients for the
; dependence on airmass in the photometric model. This tag is only present
; in "fit_params" if the tag "fit_nonlin_ext" in the input parameter
; "fit_options" has a value that is greater than or equal to "2".
;
; (xxi) a_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_col" specifying the fitted
; polynomial coefficients for the dependence on colour in the photometric model. The
; coefficients are ordered in ascending order of degree starting with the linear
; coefficient. This tag is only present in "fit_params" if the tag "fit_col" in the
; input parameter "fit_options" has a value that is greater than or equal to "1".
;
; (xxii) a_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_col" specifying the
; uncertainties in the fitted polynomial coefficients for the dependence on colour
; in the photometric model. This tag is only present in "fit_params" if the tag
; "fit_col" in the input parameter "fit_options" has a value that is greater than
; or equal to "1".
;
; (xxiii) b - DOUBLE - The fitted airmass-colour cross-term coefficient. This tag is only present in "fit_params" if the
; tag "fit_air_col" in the input parameter "fit_options" is set to "yes".
;
; (xxiv) b_err - DOUBLE - The uncertainty in the fitted airmass-colour cross-term coefficient. This tag is only present
; in "fit_params" if the tag "fit_air_col" in the input parameter "fit_options" is set to "yes".
;
; (xxv) nspatial_polyterms - LONG - The number of polynomial terms in the detector spatial coordinates x and y in the
; photometric model. This tag is only present in "fit_params" if the tag "fit_illcorr"
; in the input parameter "fit_options" has a value that is greater than or equal to "1".
;
; (xxvi) spatial_polyterms - LONG ARRAY - A 2 by "nspatial_polyterms" array of LONG values where each pair of numbers
; represents the exponents of the detector spatial coordinates x and y in each
; polynomial term. This tag is only present in "fit_params" if the tag
; "fit_illcorr" in the input parameter "fit_options" has a value that is greater
; than or equal to "1".
;
; (xxvii) c_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "nspatial_polyterms" specifying the fitted
; polynomial coefficients for the dependence on detector spatial coordinates x and y
; in the photometric model. These coefficients correspond directly to the polynomial
; terms defined by "spatial_polyterms". This tag is only present in "fit_params" if
; the tag "fit_illcorr" in the input parameter "fit_options" has a value that is
; greater than or equal to "1".
;
; (xxviii) c_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "nspatial_polyterms" specifying the
; uncertainties in the fitted polynomial coefficients for the dependence on
; detector spatial coordinates x and y in the photometric model. This tag is
; only present in "fit_params" if the tag "fit_illcorr" in the input parameter
; "fit_options" has a value that is greater than or equal to "1".
;
; (xxix) d_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_q1" specifying the fitted
; polynomial coefficients for the dependence on the first general quantity in the
; photometric model. The coefficients are ordered in ascending order of degree
; starting with the linear coefficient. This tag is only present in "fit_params" if
; the tag "fit_q1" in the input parameter "fit_options" has a value that is greater
; than or equal to "1".
;
; (xxx) d_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_q1" specifying the
; uncertainties in the fitted polynomial coefficients for the dependence on the
; first general quantity in the photometric model. This tag is only present in
; "fit_params" if the tag "fit_q1" in the input parameter "fit_options" has a
; value that is greater than or equal to "1".
;
; (xxxi) e_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_q2" specifying the fitted
; polynomial coefficients for the dependence on the second general quantity in the
; photometric model. The coefficients are ordered in ascending order of degree
; starting with the linear coefficient. This tag is only present in "fit_params" if
; the tag "fit_q2" in the input parameter "fit_options" has a value that is greater
; than or equal to "1".
;
; (xxxii) e_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "fit_options.fit_q2" specifying the
; uncertainties in the fitted polynomial coefficients for the dependence on the
; second general quantity in the photometric model. This tag is only present in
; "fit_params" if the tag "fit_q2" in the input parameter "fit_options" has a
; value that is greater than or equal to "1".
;
; (xxxiii) nq3q4_polyterms - LONG - The number of polynomial terms in the third and fourth general quantities "q3" and
; "q4" in the photometric model. This tag is only present in "fit_params" if the tag
; "fit_q3q4" in the input parameter "fit_options" has a value that is greater than
; or equal to "1".
;
; (xxxiv) q3q4_polyterms - LONG ARRAY - A 2 by "nq3q4_polyterms" array of LONG values where each pair of numbers
; represents the exponents of the third and fourth general quantities "q3" and
; "q4" in each polynomial term. This tag is only present in "fit_params" if the
; tag "fit_q3q4" in the input parameter "fit_options" has a value that is
; greater than or equal to "1".
;
; (xxxv) f_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "nq3q4_polyterms" specifying the fitted
; polynomial coefficients for the dependence on the third and fourth general
; quantities "q3" and "q4" in the photometric model. These coefficients correspond
; directly to the polynomial terms defined by "q3q4_polyterms". This tag is only
; present in "fit_params" if the tag "fit_q3q4" in the input parameter "fit_options"
; has a value that is greater than or equal to "1".
;
; (xxxvi) f_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "nq3q4_polyterms" specifying the
; uncertainties in the fitted polynomial coefficients for the dependence on the
; third and fourth general quantities "q3" and "q4" in the photometric model.
; This tag is only present in "fit_params" if the tag "fit_q3q4" in the input
; parameter "fit_options" has a value that is greater than or equal to "1".
;
; (xxxvii) npat - LONG - The number of patterns employed in the photometric model. This tag is only present in
; "fit_params" if the tag "fit_patt" in the input parameter "fit_options" is set to "yes".
;
; (xxxviii) g_coeffs - DOUBLE VECTOR - A one-dimensional vector of length "npat" specifying the fitted coefficients
; for the set of patterns in the photometric model. This tag is only present in
; "fit_params" if the tag "fit_patt" in the input parameter "fit_options" is set
; to "yes".
;
; (xxxix) g_coeffs_err - DOUBLE VECTOR - A one-dimensional vector of length "npat" specifying the uncertainties in
; the fitted coefficients for the set of patterns in the photometric model.
; This tag is only present in "fit_params" if the tag "fit_patt" in the input
; parameter "fit_options" is set to "yes".
;
; model - DOUBLE VECTOR/ARRAY - A vector/array (of the same dimensions as the input parameter "instr_mag") representing
; the fitted model instrumental magnitudes.
; chisq - DOUBLE - The chi squared of the fitted photometric model ignoring instrumental magnitude measurements with
; zero weights in "weights" and rejected instrumental magnitude measurements identified during the
; fitting process. This quantity only represents the chi squared in the case where the input weights
; "weights" represent the inverse variances for the instrumental magnitude measurements "instr_mag",
; or if the keyword ERRBAR is set (see below) and the weights represent the 1-sigma uncertainties on
; the instrumental magnitude measurements "instr_mag".
; status - INTEGER - If the fit parameters were calculated successfully and no iterations were performed, then "status"
; is returned with a value of "4". If the fit parameters were calculated successfully and the
; iterations were stopped because the algorithm tolerance was achieved, then "status" is returned
; with a value of "3". If the fit parameters were calculated successfully but the iterations were
; stopped because the maximum number of iterations "maxiter" had been performed, then "status" is
; returned with a value of "2". If the fit parameters were calculated successfully but the iterations
; were stopped because there were not enough good instrumental magnitude measurements to be used in
; the next iteration, then "status" is returned with a value of "1". If the fit parameters were not
; calculated successfully, then "status" 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" represent the
; 1-sigma uncertainties on the instrumental magnitude measurements "instr_mag", and it will calculate the actual weights
; to be used in the fit as the inverse variance weights.
;
; If the keyword FORCE_CALC_NONSTD_STAR_MAG_ERR is set (as "/FORCE_CALC_NONSTD_STAR_MAG_ERR"), then the module will
; always calculate the uncertainties in the fitted magnitudes of the non-standard stars.
;
; If the keyword XCYC_Q3Q4_DEGENERACY is set (as "/XCYC_Q3Q4_DEGENERACY"), then the module will remove terms of the form
; (q3)^N, where N is a positive even number, from the photometric model. It is necessary to set this option to avoid a
; degenerate linear regression problem when the parameters xc, yc, q3, and q4 are related as follows:
;
; (xc)^2 + (yc)^2 = (q3)^2 + (q4)^2
;
; This relation holds specifically when one is attempting to fit a static illumination correction as a function of
; detector coordinates "xc" and "yc" at the same time as attempting to fit a rotating illumination correction as a
; function of rotated detector coordinates "q3" and "q4". Note that it is the responsibility of the user to identify
; when it is necessary to set this keyword since the module will not test for the existence of the above relation
; between the parameters xc, yc, q3, and q4.
;
; If the keyword ITERATION_PAR is set to an IDL structure with the six tags described below, then the module will iterate
; the fitting process (as described under "Description"). The tags that must be present are:
;
; (i) method - STRING - This tag has two acceptable values. If "method" is set to "abs_resid", then, during each
; iteration of the fitting process, all instrumental magnitude measurements with absolute
; residuals greater than S times (see "sigma") the standard deviation of the residuals are
; flagged as candidate outliers. If "method" is set to "norm_abs_resid", then, during each
; iteration of the fitting process, all instrumental magnitude measurements with normalised
; absolute residuals greater than S, where the normalising factors are the square roots of the
; corresponding weights, are flagged as candidate outliers.
;
; (ii) sigma - FLOAT/DOUBLE - This tag specifies the sigma-clip rejection threshold to be used. If "sigma" is positive,
; then the sigma-clip threshold S is taken to be the value of "sigma". If "sigma" is
; negative or zero, then the sigma-clip threshold S is calculated as sqrt(ln(Ngood)), where
; Ngood is the number of instrumental magnitude measurements in "instr_mag" with positive
; weights. This expression for the sigma-clip threshold S may be derived from considerations
; of the Bayesian information criterion.
;
; (iii) maxrej - INTEGER/LONG or FLOAT/DOUBLE - If this tag is set to an INTEGER/LONG type positive number, then the
; value of this tag is considered to be the maximum number of instrumental
; magnitude measurements that can be rejected in any one iteration. If this
; tag is set to a FLOAT/DOUBLE type positive number that is less than or
; equal to "1.0", then the value of this tag is considered to be the
; maximum fraction of instrumental magnitude measurements that can be
; rejected in any one iteration. If this tag is set to anything else, then
; there is no limit on the number of instrumental magnitude measurements
; that can be rejected in any one iteration.
;
; (iv) permanent - INTEGER/LONG - If this tag is set to "1", then instrumental magnitude measurements that are rejected
; will remain rejected for all subsequent iterations, meaning that the set of instrumental
; magnitude measurements used at each iteration will only diminish. If this tag is set to
; any other value, then instrumental magnitude measurements will not be permanently
; rejected so that if an instrumental magnitude measurement is initially excluded then it
; may be subsequently included in the fitting process during the later iterations.
;
; (v) tol - FLOAT/DOUBLE - This tag specifies the tolerance of the fitting process. The iterations will stop if the
; maximum fractional change in the fit parameters between subsequent iterations is less than or
; equal to "tol". This parameter must have a value greater than or equal to "0.0", and less than
; "1.0". A value for "tol" of "0.0" means that the iterations will continue until none of the fit
; parameters change from one iteration to the next.
;
; (vi) maxiter - INTEGER/LONG - This tag specifies the maximum number of iterations to be performed before returning the
; fit parameters. If this parameter is set to a negative value or zero, then there will be
; no constraint on the maximum number of iterations that may be performed.
;
; If the keyword EXTRA_INFO is set to a named variable, then, on return, this variable will contain an IDL structure with
; the following tags:
;
; (i) ndata - LONG - The number of instrumental magnitude measurements in the input parameter "instr_mag".
; (ii) ndata_good - LONG - The initial number of instrumental magnitude measurements with positive weights.
; (iii) ndata_used - LONG - The number of instrumental magnitude measurements used in the calculation of the final fit
; parameters.
; (iv) niter - LONG - The number of iterations performed in the fitting process.
;
; If the keyword DATA_USED_SUBS is set to a named variable, then, on return, this variable will contain a VECTOR of LONG
; type numbers representing the subscripts for the instrumental magnitude measurements that were used in the calculation
; of the final fit parameters.
;
; If the keyword QUIET is set (as "/QUIET"), then the module will not print any progress messages on screen. This
; functionality is useful if the module is to be called many times within another routine.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 23/03/2011 - Module created (dmb).
;If the keyword QUIET is set, then do not print progress messages
;Set the default output parameter values
;Check that "instr_mag" is of the correct number type, and that it has at least two elements
;If "weights" does not have the same number of elements as "instr_mag" or the correct number type, then weight all instrumental magnitude
;measurements equally, otherwise set any negative weights equal to zero while checking that not all instrumental magnitude measurements
;are flagged as bad. Also, if the keyword ERRBAR is set, then convert the 1-sigma uncertainties on the instrumental magnitude
;measurements to inverse variances.
;Check the parameters "fit_options", "star_id", "std_star_id", "std_star_mag", "std_star_colour", "airmass", "xc", "yc",
;"q1", "q2", "q3", "q4", "patt_arr", "group_id_zp", and "group_id_ext". Also, where appropriate, associate the standard
;magnitudes (and standard colours if necessary) with the instrumental magnitude measurements.
;Sort the star names and rearrange the associated input data accordingly, extracting data from the input parameters
;where necessary
;Report the number of unique stars and the breakdown into standard and non-standard stars
;If the photometric model requires the use of the input parameter "group_id_zp"
;Determine the set of unique measurement groups for "group_id_zp"
;Check that "group_id_zp" contains at least one non-empty string
;If necessary, remove the empty string from the set of unique measurement groups for "group_id_zp"
;Report the number of unique measurement groups for "group_id_zp"
;If the photometric model requires the use of the input parameter "group_id_ext"
;Determine the set of unique measurement groups for "group_id_ext"
;Determine if the fitting process should be iterated
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Determine the number of free parameters in the photometric model
;Determine the number of free parameters in the photometric model and define any polynomial terms where necessary
;Check that the linear regression problem is over-determined or exactly-determined
;Determine the number of parameters in the photometric model that are not non-standard star magnitudes
;If necessary, determine the subscripts of the diagonal elements of the lower-right sub-matrix of the least
;squares matrix
;Add the relevant information at this point to the output parameter "fit_params"
;Subtract the standard magnitudes from the instrumental magnitude measurements where relevant
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Set up an internal pattern array for the relevant terms of the photometric model
;If necessary, set up an internal pattern array for the relevant terms of the photometric model
;If necessary, prepare the patterns for the polynomial terms in airmass in the photometric model
;If necessary, prepare the patterns for the polynomial terms in colour in the photometric model
;If necessary, prepare the pattern for the airmass-colour cross-term in the photometric model
;If necessary, prepare the patterns for the polynomial terms in the detector spatial coordinates in the photometric model
;If necessary, prepare the patterns for the polynomial terms in the first general quantity in the photometric model
;If necessary, prepare the patterns for the polynomial terms in the second general quantity in the photometric model
;If necessary, prepare the patterns for the polynomial terms in the third and fourth general quantities "q3" and "q4"
;in the photometric model
;If necessary, insert the patterns stored in the input parameter "patt_arr" into the internal pattern array
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;For each non-standard star, determine the corresponding subscripts in the set of input data
;If there is at least one star without a standard magnitude
;For each non-standard star, determine the corresponding subscripts in the set of input data
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Iterative fitting loop
;Start the iterative fitting loop
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Calculate the least squares matrix and vector
;If this is the first iteration
;Calculate the least squares matrix and the vector on the right hand side
;If the iteration schema requires it, then save the original least squares matrix and the vector on the right hand
;side
;If this is not the first iteration
;Record the previous set of fit parameters
;If instrumental magnitude measurements are not being permanently rejected, then reset the least squares matrix and
;the vector on the right hand side
;In this case, it is faster to subtract the contributions of the rejected instrumental magnitude measurements from
;the least squares matrix and the vector on the right hand side, rather than recalculating everything from scratch
;Check that there are no zero diagonal elements in the least squares matrix
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Solve the normal equations
;Calculate the best fit parameters and their associated uncertainties
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Calculate the model and residuals
;Construct the current photometric model for the instrumental magnitude measurements
;Calculate the squared residuals of the current fit
;Calculate the chi squared of the current fit
;Update the number of iterations performed
;If no iterations are to be performed, then exit from the iterative fitting loop
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Iterative schema
;Save a copy of the current weights
;If this is not the first iteration
;Calculate the maximum fractional change in the fit parameters
;If the maximum fractional change in the fit parameters is less than or equal to "tol", then exit the iterative
;fitting loop
;If the maximum number of iterations has been reached, then exit the iterative fitting loop
;If iteration is being performed based on the absolute residuals of the fit
;Only perform instrumental magnitude measurement rejection if there are more data points than fit parameters
;Estimate the variance of the residuals
;If instrumental magnitude measurements are not to be rejected permanently, then reset the current weights
;to the original weights
;Determine a set of candidate outlier instrumental magnitude measurements
;If iteration is being performed based on the normalised absolute residuals of the fit
;If instrumental magnitude measurements are not to be rejected permanently, then reset the current weights
;to the original weights
;Determine a set of candidate outlier instrumental magnitude measurements
;If no (further) instrumental magnitude measurements are to be rejected, then exit the iterative fitting loop
;If a limit has been set on the number of instrumental magnitude measurements that may be rejected in any one
;iteration, then determine what this limit is for the current iteration
;If not all candidate outlier instrumental magnitude measurements are to be rejected in this iteration
;Determine the required set of candidate outlier instrumental magnitude measurements with the largest residuals
;Reject the outlier instrumental magnitude measurements and determine the new number of good instrumental
;magnitude measurements
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;Set the output parameters
;Create an output structure containing the fitted parameters and their uncertainties, at the same time as reporting
;these values to the user
;Set the remaining output parameter values
;If the fitting process was iterated
;Set the output parameter values in the IDL structure "extra_info"
;Determine the subscripts of the instrumental magnitude measurements used in the final fit
;Report the properties of the final fit
;If the iterative fitting loop was exited because the fit tolerance was achieved, then set "status" to "3"
;and finish
;If the iterative fitting loop was exited because the maximum number of iterations was reached, then set
;"status" to "2" and finish
;If the iterative fitting loop was exited because there were not enough good instrumental magnitude
;measurements to be used in the next iteration, then set "status" to "1" and finish
;If the fitting process was not iterated
;Set the output parameter values in the IDL structure "extra_info"
;Determine the subscripts of the instrumental magnitude measurements used in the fit
;Set "status" to "4"