Estimates implicit and/or explicit functions of parameters (W.M. Patefield).
Options
PRINT = string token |
What to print (estimates , correlations , monitoring ); default esti |
---|---|
NOMESSAGE = string token |
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 token |
Control for exit on fault detection (job , procedure ); default job for batch jobs, proc for interactive |
ZCALCULATION = expression structures |
Specify the calculation of ZERO and DZBIMPLICIT |
DZPCALCULATION = expression structures |
Specify the calculation of DZBPARAMETER |
ECALCULATION = expression structures |
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 -1010 |
UPPER = variate |
Upper bounds to IMPLICIT functions; default +1010 |
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 106.
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.
See also
Commands for: Regression analysis.
Example
CAPTION 'IFUNCTION example',\ !t('The first example uses the procedure to solve simultaneous',\ 'nonlinear equations.'),\ !t('The second example obtains estimates of both implicit and',\ 'explicit functions of parameters.'),\ 'Example 1: Find the points where the ellipse',\ ' 5 x*x + 16 y*y + 12 x*y - 22 x - 44 y + 29 = 0',\ 'intersects the unit circle', \ ' x*x + y*y - 1 = 0'; STYLE=meta,6(plain) " Set up expressions to calculate the two functions as elements of the variate f and their derivatives as elements of the 2 by 2 matrix df. The i'th row of df contains the derivatives of f$[i] with respect to x and y (i = 1,2). " EXPRESSION [VALUE=f$[1]=5*x*x+16*y*y+12*x*y-22*x-44*y+29 ] Calcf[1] & [VALUE=f$[2]=x*x+y*y-1] Calcf[2] & [VALUE=df$[1,1,2,2;1,2,1,2]=\ (10,12,2,0)*x+(12,32,0,2)*y-(22,44,0,0) ] Calcf[3] " To find both solutions to the equations, use IFUNCTION twice with different initial values (0,1) and (1,0) for (x,y). With the default PRINT=estimates of the PRINT option, the solutions are printed together with the final values of the variate f. " IFUNCTION [ZCALCULATION=Calcf[]] IMPLICIT=2(!P(x,y)); ZERO=f;\ DZBIMPLICIT=df; INITIAL=!(0,1),!(1,0) CAPTION 'Example 2' " declare factors Block, Plot and Nrate for a randomized block design with three blocks and five treatments per block " FACTOR [LABELS=!T(a,b,c);VALUES=5(1...3)] Block FACTOR [LEVELS=!(0,0.1,0.2,0.4,0.8);VALUE=(0,0.1,0.2,0.4,0.8)3] Nrate & [LEVELS=5; VALUE=(1...5)3] Plot " read Yield data " VARIATE [NVALUES=15] Yield; EXTRA=' ( from cutting plots NorthWyke 1985)' READ Yield 5.951 9.0845 10.864 12.095 11.026 4.8875 7.084 10.330 13.60185 14.365 6.898 9.697 11.618 13.0966 12.266 : " ANOVA " BLOCKSTRUCTURE Block/Plot TREATMENTSTRUCTURE Nrate ANOVA [PRINT=aovtable,means; FPROBABILITY=yes; NOMESSAGE=residual] Yield " Keep table of means and residual d.f. and s.s. " AKEEP Nrate; MEANS=Tmeans AKEEP Block.Plot; DF=Resdf; SS=Resss CALCULATE Resms=Resss/Resdf ENQUIRE Chan; FILETYPE=output; OUTSTYLE=Style OUTPUT [STYLE=plain] PRINT !T(' a + b * X ',\ ' Y = -------------------- ',\ ' 1 + c * X + d * X**2 ',\ ' ',\ ' Y = Yield ; X = Nrate '); JUST=left OUTPUT [STYLE=#Style] VARIATE [VALUES=#Nrate] X " obtain initial values of the parameters a and b as a = mean Yield (at X=0) and b = slope between X=0 and X=0.1 and of c and d by fitting ( a + b * X ) / Yield - 1 = c * X + d * X**2 " SCALAR a,b,c,d,y1 EQUATE Tmeans;!P(a,y1) CALCULATE b=10*(y1-a) & Y2=(a+b*X)/Yield-1 & Xsqrd=X**2 MODEL Y2 FIT [CONSTANT=omit; PRINT=*] X,Xsqrd RKEEP ESTIMATES=cd EQUATE cd; !P(c,d) " Set up an expression for fittedvalues of the model " EXPRESSION Calcfitted; VALUE=!E(Fitted=(a+b*Nrate)/(1+Nrate*(c+d*Nrate))) CAPTION 'Fit the model using FITNONLINEAR' MODEL [DISPERSION=Resms] Yield; FITTEDVALUES=Fitted RCYCLE a,b,c,d FITNONLINEAR [CALCULATION=Calcfitted; CONSTANT=OMIT] " Keep the variance-covariance matrix obtained with DISPERSION=Resms " RKEEP VCOVARIANCE=Vcov " Set up expressions for explicit calculation of N0 and Y0 , the Nitrogen application and corresponding yield at which the yield is a maximum. " EXPRESSION [VALUE=N0=(SQRT((ad=a*d)**2+(bd=b*d)*(b-a*c))-ad)/bd] CalN0 & [VALUE=Y0=(a+b*N0)/(1+N0*(c+d*N0))] CalY0 CAPTION 'Estimate N0 and Y0 using RFUNCTION' RFUNCTION [CALCULATION=CalN0,CalY0] N0,Y0 " declare variate Gradval with values so that procedure IFUNCTION can be used to obtain the values of X and Y for which the response rate dY/dX = 0,5,10,15 and pointers N and Y for their respective values " VARIATE [VALUES=0,5,10,15] Gradval POINTER [SUFFIXES=Gradval] N,Y VARIATE [NVALUE=4] Vy,Vn DIAGONALMATRIX [ROWS=4] Diagmat " Set up expressions to calculate the variates Zero = dY/dX - Gradval Dzbydx = d(Zero)/dX and put Dzbydx into the diagonal of the 4 by 4 matrix Dzbyimplicit " EXPRESSION [VALUE=Vn$[1...4]=N[] ] Zcalc[1] & [VALUE=Zero=(Dybydx=(Num=b-a*c-d*Vn*(2*a+b*Vn))/ \ (Densqd=(Den=1+Vn*(c+d*Vn))**2))-Gradval] Zcalc[2] & [VALUE=Dzbydx=-2*((Den*d*(a+b*Vn))+Num*(c+2*d*Vn))/ \ (Dencub=Den*Densqd)] Zcalc[3] & [VALUE=Dzbyimplicit=(Diagmat=Dzbydx)] Zcalc[4] " Set up expressions to calculate the matrix of derivatives of Zero with respect to the parameters a,b,c,d Dzbypar = d(Zero)/d(a,b,c,d) " EXPRESSION [VALUE=Dzbypar$[*;1]=(-c-2*d*Vn)/Densqd] Dzpcalc[1] & [VALUE=Dzbypar$[*;2]=(1-d*Vn*Vn)/Densqd] Dzpcalc[2] & [VALUE=Dzbypar$[*;3]=(-a*Den-2*Vn*Num)/Dencub] Dzpcalc[3] & [VALUE=Dzbypar$[*;4]=-Vn*((2*a+b*Vn)*Den+2*Num*Vn)/Dencub]\ Dzpcalc[4] " Set up expressions to calculate the explicit function Y[] of both the parameters (a,b,c,d) and of the implicit function N[]. From previous calculated expression the values of N[] are stored in the variate Vn. Also set up expressions for calculation of the matrices of derivatives of the explicit functions with respect to the parameters:- Dybypar = dY[]/d(a,b,c,d) and with respect to the implicit functions:- Dybydn, the 4 by 4 matrix with diagonal elements given by the previously calculated variate Dybydx. " EXPRESSION [VALUE=Vy=(a+b*Vn)/Den] Ycalc[1] & [VALUE=Y[]=Vy$[1...4]] Ycalc[2] & [VALUE=Dybypar$[*;1]=1/Den] Ycalc[3] & [VALUE=Dybypar$[*;2]=Vn/Den] Ycalc[4] & [VALUE=Dybypar$[*;3]=-Vy*Vn/Den] Ycalc[5] & [VALUE=Dybypar$[*;4]=-Vy*Vn*Vn/Den] Ycalc[6] & [VALUE=Dybydn=(Diagmat=Dybydx)] Ycalc[7] CALCULATE Initn=MEAN(Nrate) CAPTION !T('Use procedure IFUNCTION to calculate the implicit functions',\ 'N[0,5,10,15] of the parameters a,b,c,d (Nitrogen applications',\ 'at which the response rate is 0,5,10,15 respectively)', 'and the explicit functions Y[0,5,10,15] of both the implicit',\ 'functions and the parameters (corresponding Yield estimates).') IFUNCTION [NPARAMETER=4; ZCALCULATION=Zcalc[]; DZPCALCULATION=Dzpcalc[];\ ECALCULATION=Ycalc[]] IMPLICIT=N; ZERO=Zero;\ DZBIMPLICIT=Dzbyimplicit; DZBPARAMETER=Dzbypar;\ INITIAL=!(4(Initn)); EXPLICIT=Y; DEBPARAMETER=Dybypar;\ DEBIMPLICIT=Dybydn; VCOVARIANCE=Vcov