IFUNCTION procedure

Estimates implicit and/or explicit functions of parameters (W.M. Patefield).

Options

PRINT = string

What to print (estimates, correlations, monitoring); default esti

NOMESSAGE = string

Which warning messages to suppress (parameter, convergence); default *

NPARAMETER = scalar

Number of parameters; default zero

MAXCYCLE = scalar

Maximum number of iterations; default 20

STRINGENCY = scalar

Stringency of tests for convergence, 0,1,2...etc; default 5

EXITCONTROL = string

Control for exit on fault detection (job, procedure); default job for batch jobs, proc for interactive

ZCALCULATION = expressions

Specify the calculation of ZERO and DZBIMPLICIT

DZPCALCULATION = expressions

Specify the calculation of DZBPARAMETER

ECALCULATION = expressions

Specify the calculation of EXPLICIT, DEBPARAMETER and DEBIMPLICIT

Parameters

IMPLICIT = variate or pointer to scalars

Implicit functions

INITIAL = variate

Initial values for IMPLICIT functions

LOWER = variate

Lower bounds to IMPLICIT functions; default -10¹⁰

UPPER = variate

Upper bounds to IMPLICIT functions; default +10¹⁰

VCOVARIANCE = symmetric matrix

Variance-covariance matrix of parameter estimates

ZERO = variate

Equations defining implicit functions (values calculated by ZCALCULATION)

DZBIMPLICIT = matrix

First derivatives of equations ZERO with respect to implicit functions IMPLICIT (values calculated by ZCALCULATION); rows correspond to ZERO, columns correspond to IMPLICIT

DZBPARAMETER = matrix

First derivatives of equations ZERO with respect to parameters (must not be set for NPARAMETER=0; values calculated by DZPCALCULATION); rows correspond to ZERO, columns to parameters

DIBPARAMETER = matrix

First derivatives of IMPLICIT functions with respect to parameters (must not be set for NPARAMETER=0); rows correspond to IMPLICIT, columns correspond to parameters

EXPLICIT = variate or pointer to scalars

Explicit functions of parameters and/or implicit functions (values calculated by ECALCULATION)

DEBPARAMETER = matrix

First partial derivatives of EXPLICIT functions with respect to parameters (values calculated by ECALCULATION); rows correspond to EXPLICIT, columns correspond to parameters

DEBIMPLICIT = matrix

First partial derivatives of EXPLICIT functions with respect to IMPLICIT functions (values calculated by ECALCULATION); rows correspond to EXPLICIT, columns correspond to IMPLICIT

DFBPARAMETER = matrix

First derivatives of ESTIMATES with respect to parameters; rows correspond to ESTIMATES, columns correspond to parameters

ESTIMATES = variate

Estimates of IMPLICIT and EXPLICIT functions

SE = variate

Standard errors of ESTIMATES

CORRELATIONS = symmetric matrix

Correlation matrix of ESTIMATES

FCOVARIANCE = symmetric matrix

Variance-covariance matrix of ESTIMATES

Description

IFUNCTION solves implicit equations of functions of parameters. The equations are specified by the variate ZERO, the ith element defining the ith equation in terms of the IMPLICIT functions. The parameters ZERO and IMPLICIT must be of the same length (n), IMPLICIT being either a variate or a pointer to n scalars. The option ZCALCULATION supplies expressions for the calculation of both ZERO and the n by n matrix DZBIMPLICIT of first derivatives of ZERO with respect to the IMPLICIT functions. The element in the ith row and jth column of DZBIMPLICIT is the (partial) derivative of the ith element of ZERO with respect to the jth element of IMPLICIT. DZBIMPLICIT is initialized to zero and hence only non-zero elements need be calculated by ZCALCULATION.

The values of the IMPLICIT functions satisfying ZERO = 0 are obtained iteratively. Initial values may be given as a variate in the parameter INITIAL. If INITIAL is not set any current values of IMPLICIT are used as initial values. Output is controlled by the PRINT option. The option NOMESSAGE allows warning messages to be suppressed. The option MAXCYCLE and the parameters LOWER and UPPER are similar in their effect to their use in the RCYCLE directive. The option STRINGENCY controls the stringency with which tests for convergence are applied, higher values being more stringent. The option EXITCONTROL controls the action on fault detection. IFUNCTION may be used to solve n simultaneous nonlinear equations in n unknowns (the IMPLICIT functions) by not setting the NPARAMETER option (or setting it to zero). More generally, the variate ZERO is a function of both the IMPLICIT functions and NPARAMETER parameter estimates from a model previously fitted using FIT, FITCURVE or FITNONLINEAR. The DZPCALCULATION option supplies expressions for calculation of the n by NPARAMETER matrix DZBPARAMETER of (partial) derivatives of ZERO with respect to the model parameters (only non-zero elements need be calculated).

In addition (or instead) m explicit functions of the model parameters and/or the IMPLICIT functions may be specified by the parameter EXPLICIT, a variate of length m or a pointer to m scalars. The (partial) derivatives of the EXPLICIT functions with respect to the model parameters are given by the m by NPARAMETER matrix DEBPARAMETER and the (partial) derivatives with respect to the IMPLICIT functions by the m by n matrix DEBIMPLICIT. If either of these matrices is not set, then it is taken to be zero (i.e. the EXPLICIT functions do not depend on the model parameters or the IMPLICIT functions respectively). Expressions for calculating EXPLICIT, DEBPARAMETER and DEBIMPLICIT are supplied by the option ECALCULATION, the two matrices being initialized to zero and hence only their non-zero elements need be calculated. For EXPLICIT functions dependent on model parameters only (i.e. not on any IMPLICIT functions), ECALCULATION need not be set, in which case their values must be supplied by EXPLICIT and their (partial) derivatives with respect to model parameters by DEBPARAMETER on entry to IFUNCTION.

The parameters ZERO, DZBIMPLICIT, DZBPARAMETER, DEBPARAMETER and DEBIMPLICIT entering into the calculations ZCALCULATION, DZPCALCULATION and ECALCULATION need not be declared before using IFUNCTION. If they are declared they must have the correct attributes. The only exception to this is when derivatives of the EXPLICIT functions are supplied directly in the matrix DEBPARAMETER rather than obtained by calculations using ECALCULATION.

It is essential that the expressions for calculating DZBIMPLICIT are formulated correctly. If they are not, faults such as divergence of the optimization algorithm or estimates becoming out of bounds may be detected and reported. Fault CA16 may also be caused by incorrectly calculating DZBIMPLICIT as a singular matrix.

The variance-covariance matrix of the fitted parameters is supplied by the parameter VCOVARIANCE containing the variance-covariance matrix from a previous FIT, FITCURVE or FITNONLINEAR.

Estimates of all n+m functions (n IMPLICIT and m EXPLICIT functions of parameters) are saved by the parameter ESTIMATES. Their derivatives with respect to the model parameters are saved by the parameter DFBPARAMETER. Their variance-covariance matrix is saved by the parameter FCOVARIANCE. The standard errors of, and correlations between, the ESTIMATES are saved by the parameters SE and CORRELATIONS.

Options: PRINT, NOMESSAGE, NPARAMETER, MAXCYCLE, STRINGENCY, EXITCONTROL, ZCALCULATION, DZPCALCULATION, ECALCULATION.

Parameters: IMPLICIT, INITIAL, LOWER, UPPER, VCOVARIANCE, ZERO, DZBIMPLICIT, DZBPARAMETER, DIBPARAMETER, EXPLICIT, DEBPARAMETER, DEBIMPLICIT, DFBPARAMETER, ESTIMATES, SE, CORRELATIONS, FCOVARIANCE.

Method

The implicit functions are calculated by solving the simultaneous equations ZERO = 0 iteratively using Newton-Raphson. It is assumed that a solution exists and that the initial values are sufficiently close to a solution for the optimization to converge. Poor initial values can lead to divergence. A warning message is given when divergence is detected. Reasonable initial values may be obtained by using FITNONLINEAR to minimize the function k × MAX( ABS(ZERO) ), with k equal to a large number such as 10⁶.

A maximum of three convergence criteria may be employed. They are:

(i) the Increment criterion defined as MAX( ABS(Inc) / MAX( ABS(IMPLICIT), 1 ) ), where Inc is the variate of implicit function increments in the iterative process,

(ii) the Zero criterion defined as MAX( ABS(ZERO) / Scaling-variate ) where the Scaling-variate is the greater of the maximum value of ZERO over all cycles of the iterative process and 0.0001, and

(iii) the Gradient criterion defined as ABS( T(Inc) *+ DZBIMPLICIT *+ Inc ).

The values of criterion (ii) may be highly dependent on the initial parameter values and criterion (iii) is of use primarily when the equations ZERO = 0 are derivatives of a scalar function and DZBIMPLICIT is the matrix of second derivatives of the function.

Convergence is completed when criterion (i) cannot be further reduced. However the iterative process continues searching for lower values until other criteria cannot be further reduced. The criteria involved are determined by the STRINGENCY option. For STRINGENCY = 0 or 1 only criterion (i) is used. For STRINGENCY = 2 or 3 criterion (ii) is also used. STRINGENCY = 1 or 3 requires convergence at two successive iterations. For STRINGENCY = 4 or 5 all criteria are used, STRINGENCY = 5 requiring convergence of both criteria (i) and (ii) at two successive iterations. Higher values of STRINGENCY require convergence of all three criteria at increasing numbers of successive iterations.

The default STRINGENCY value of 5 is recommended at least until the expressions for calculations are validated. Low values may give convergence at incorrect values of the implicit functions, particularly with poor INITIAL values when the equations ZERO are not approximately linear. High values will often result in an unneccessarily large number of iterations. IFUNCTION calculates the matrix DIBPARAMETER of derivatives of the implicit functions with respect to the model parameters (Marsden, 1984, page 211). The matrices DEBPARAMETER and DEBIMPLICIT of partial derivatives of any explicit functions with respect to the model parameters and the implicit functions respectively are evaluated using expressions supplied in ECALCULATION. By the chain rule, the derivatives of the explicit functions with respect to the parameters are given by

DEBPARAMETER + ( DEBIMPLICIT *+ DIBPARAMETER ).

This matrix is appended to DIBPARAMETER to form the n+m by NPARAMETER matrix DFBPARAMETER of derivatives of the length n+m variate

ESTIMATES = !( #IMPLICIT, #EXPLICIT )

with respect to the model parameters.

The variance-covariance matrix of model parameters resulting from a previous FIT, FITCURVE or FITNONLINEAR is supplied by the parameter VCOVARIANCE, and the variance-covariance matrix of the ESTIMATES of both the implicit and explicit functions is computed as

FCOVARIANCE = QPRODUCT(DFBPARAMETER; VCOVARIANCE).

Action with RESTRICT

None of the parameters of IFUNCTION may be restricted.

Reference

Marsden, J.E. (1984). Elementary Classical Analysis. W.H. Freeman and Company, San Francisco.