1. Home
  2. IFUNCTION procedure

IFUNCTION procedure

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


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


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


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.




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


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


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


Action with RESTRICT

None of the parameters of IFUNCTION may be restricted.


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

See also

Commands for: Regression analysis.


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. "
           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      [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
OUTPUT     [STYLE=plain]
PRINT   !T('                        a + b * X            ',\ 
           '             Y  =   --------------------     ',\
           '                    1 + c * X + d * X**2     ',\
           '                                             ',\ 
           '             Y = Yield ;  X = Nrate          '); JUST=left
OUTPUT     [STYLE=#Style]
" 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
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'
RCYCLE     a,b,c,d
" Keep the variance-covariance matrix obtained with DISPERSION=Resms "
" 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'
" 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
" 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]\ 
" 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]
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).')
           ECALCULATION=Ycalc[]] IMPLICIT=N; ZERO=Zero;\ 
           DZBIMPLICIT=Dzbyimplicit; DZBPARAMETER=Dzbypar;\ 
           INITIAL=!(4(Initn)); EXPLICIT=Y; DEBPARAMETER=Dybypar;\ 
Updated on March 7, 2019

Was this article helpful?