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 -10^{10} |

`UPPER` = variate |
Upper bounds to `IMPLICIT` functions; default +10^{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 *i*th element defining the *i*th 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 *i*th row and *j*th column of `DZBIMPLICIT`

is the (partial) derivative of the *i*th element of `ZERO`

with respect to the *j*th 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^{6}.

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