GFNIN
This function evaluates the inverse of a general continuous cumulative distribution function given in a subprogram.
Function Return Value
GFNIN — The inverse of the function F at the point P. (Output)
F(GFNIN) is “close” to P.
Required Arguments
F — User‑supplied FUNCTION to be inverted. F must be continuous and strictly monotone. The form is F(X), where
X — The argument to the function. (Input)
F — The value of the function at X. (Output)
F must be declared EXTERNAL in the calling program.
P — The point at which the inverse of F is desired. (Input)
GUESS — An initial estimate of the inverse of F at P. (Input)
Optional Arguments
EPS — Convergence criterion. (Input)
When the relative change in GFNIN from one iteration to the next is less than EPS, convergence is assumed. A common value for EPS is 0.0001. Another common value is 100 times the machine epsilon.
Default: EPS = 100 times the machine epsilon.
FORTRAN 90 Interface
Generic: GFNIN (F, P, GUESS [, …])
Specific: The specific interface names are S_GFNIN and D_GFNIN.
FORTRAN 77 Interface
Single: GFNIN (F, P, EPS, GUESS)
Double: The double precision name is DGFNIN.
Description
Function GFNIN evaluates the inverse of a continuous, strictly monotone function. Its most obvious use is in evaluating inverses of continuous distribution functions that can be defined by a FORTRAN function. If the distribution function cannot be specified in a FORTRAN function, but the density function can be evaluated at a number of points, then routine GCIN can be used.
Function GFNIN uses regula falsi and/or bisection, possibly with the Illinois modification (see Dahlquist and Bjorck 1974). A maximum of 100 iterations are performed.
Comments
1. Informational errors
|
Type |
Code |
Description |
|
4 |
1 |
After 100 attempts, a bound for the inverse cannot be determined. Try again with a different initial estimate. |
|
4 |
2 |
No unique inverse exists. |
|
4 |
3 |
Over 100 iterations have occurred without convergence. Convergence is assumed. |
2. The function to be inverted need not be a distribution function, it can be any continuous, monotonic function.
Example
In this example, we find the 99–th percentage point for an F random variable with 1 and 7 degrees of freedom. (This problem could be solved easily using routine FIN. Compare the example for FIN). The function to be inverted is the F distribution function, for which we use routine FDF. Since FDF requires the degrees of freedom in addition to the point at which the function is evaluated, we write another function F that receives the degrees of freedom via a common block and then calls FDF. The starting point (initial guess) is taken as two standard deviations above the mean (since this would be a good guess for a normal distribution). It is not necessary to supply such a good guess. In this particular case, an initial estimate of 1.0, for example, yields the same answer in essentially the same number of iterations. (In fact, since the F distribution is skewed, the initial guess, 7.0, is really not that close to the final answer.)
USE UMACH_INT
USE GFNIN_INT
IMPLICIT NONE
INTEGER NOUT
REAL DFD, DFN, F, F0, GUESS, P, SQRT
COMMON /FCOM/ DFN, DFD
INTRINSIC SQRT
EXTERNAL F
!
CALL UMACH (2, NOUT)
P = 0.99
DFN = 1.0
DFD = 7.0
! Compute GUESS as two standard
! deviations above the mean.
GUESS = DFD/(DFD-2.0) + 2.0*SQRT(2.0*DFD*DFD*(DFN+DFD-2.0)/(DFN* &
(DFD-2.0)**2*(DFD-4.0)))
F0 = GFNIN(F,P,GUESS)
WRITE (NOUT,99999) F0
99999 FORMAT (' The F(1,7) 0.01 critical value is ', F6.3)
END
!
REAL FUNCTION F (X)
REAL X
!
REAL DFD, DFN, FDF
COMMON /FCOM/ DFN, DFD
EXTERNAL FDF
!
F = FDF(X,DFN,DFD)
RETURN
END
Output
The F(1,7) 0.01 critical value is 12.246
