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