NAG Library Function Document

nag_deviates_f_vector (g01tdc)

void	nag_deviates_f_vector (Integer ltail, const Nag_TailProbability tail[], Integer lp, const double p[], Integer ldf1, const double df1[], Integer ldf2, const double df2[], double f[], Integer ivalid[], NagError *fail)

3 Description

The deviate,

f_{p_{i}}

, associated with the lower tail probability,

p_{i}

, of the

F

-distribution with degrees of freedom

u_{i}

and

v_{i}

is defined as the solution to

P (F_{i} \leq f_{p_{i}} : u_{i}, v_{i}) = p_{i} = \frac{u_{i}^{\frac{1}{2} u_{i}} v_{i}^{\frac{1}{2} v_{i}} Γ (\frac{u_{i} + v_{i}}{2})}{Γ (\frac{u_{i}}{2}) Γ (\frac{v_{i}}{2})} \int_{0}^{f_{p_{i}}} {F_{i}}^{\frac{1}{2} (u_{i} - 2)} {(v_{i} + u_{i} F_{i})}^{- \frac{1}{2} (u_{i} + v_{i})} d F_{i},

where

u_{i}, v_{i} > 0

;

0 \leq f_{p_{i}} < \infty

The value of

f_{p_{i}}

is computed by means of a transformation to a beta distribution,

P_{i β_{i}} (B_{i} \leq β_{i} : a_{i}, b_{i})

P (F_{i} \leq f_{p_{i}} : u_{i}, v_{i}) = P_{i β_{i}} (B_{i} \leq \frac{u_{i} f_{p_{i}}}{u_{i} f_{p_{i}} + v_{i}} : u_{i} / 2, v_{i} / 2)

and using a call to nag_deviates_beta_vector (g01tec).

For very large values of both

u_{i}

and

v_{i}

, greater than

10^{5}

, a Normal approximation is used. If only one of

u_{i}

v_{i}

is greater than

10^{5}

then a

χ^{2}

approximation is used; see Abramowitz and Stegun (1972).

The input arrays to this function are designed to allow maximum flexibility in the supply of vector arguments by re-using elements of any arrays that are shorter than the total number of evaluations required. See Section 2.6 in the g01 Chapter Introduction for further information.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

5 Arguments

1: ltail – IntegerInput

On entry: the length of the array tail.

Constraint:

ltail > 0

2: tail[ltail] – const Nag_TailProbabilityInput

On entry: indicates which tail the supplied probabilities represent. For

j = (i - 1) mod ltail

, for

i = 1, 2, \dots, \max (ltail, lp, ldf1, ldf2)

$tail [j] = Nag_LowerTail$: The lower tail probability, i.e., $p_{i} = P (F_{i} \leq f_{p_{i}} : u_{i}, v_{i})$ .
$tail [j] = Nag_UpperTail$: The upper tail probability, i.e., $p_{i} = P (F_{i} \geq f_{p_{i}} : u_{i}, v_{i})$ .

Constraint:

tail [j - 1] = Nag_LowerTail

Nag_UpperTail

, for

j = 1, 2, \dots, ltail

3: lp – IntegerInput

On entry: the length of the array p.

Constraint:

lp > 0

4: p[lp] – const doubleInput

On entry:

p_{i}

, the probability of the required

F

-distribution as defined by tail with

p_{i} = p [j]

j = (i - 1) mod lp

Constraints:

if $tail [k] = Nag_LowerTail$ , $0.0 \leq p [j] < 1.0$ ;
otherwise $0.0 < p [j] \leq 1.0$ .

Where

k = (i - 1) mod ltail

and

j = (i - 1) mod lp

5: ldf1 – IntegerInput

On entry: the length of the array df1.

Constraint:

ldf1 > 0

6: df1[ldf1] – const doubleInput

On entry:

u_{i}

, the degrees of freedom of the numerator variance with

u_{i} = df1 [j]

j = (i - 1) mod ldf1

Constraint:

df1 [j - 1] > 0.0

, for

j = 1, 2, \dots, ldf1

7: ldf2 – IntegerInput

On entry: the length of the array df2.

Constraint:

ldf2 > 0

8: df2[ldf2] – const doubleInput

On entry:

v_{i}

, the degrees of freedom of the denominator variance with

v_{i} = df2 [j]

j = (i - 1) mod ldf2

Constraint:

df2 [j - 1] > 0.0

, for

j = 1, 2, \dots, ldf2

9: f[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array f must be at least

\max (ltail, lp, ldf1, ldf2)

On exit:

f_{p_{i}}

, the deviates for the

F

-distribution.

10: ivalid[ $\dim$ ] – IntegerOutput

Note: the dimension, dim, of the array ivalid must be at least

\max (ltail, lp, ldf1, ldf2)

On exit:

ivalid [i - 1]

indicates any errors with the input arguments, with

$ivalid [i - 1] = 0$

No error.

$ivalid [i - 1] = 1$

On entry,

invalid value supplied in tail when calculating

f_{p_{i}}

$ivalid [i - 1] = 2$

On entry,

invalid value for

p_{i}

$ivalid [i - 1] = 3$

On entry,	$u_{i} \leq 0.0$ ,
or	$v_{i} \leq 0.0$ .

$ivalid [i - 1] = 4$

The solution has not converged. The result should still be a reasonable approximation to the solution.

$ivalid [i - 1] = 5$

The value of

p_{i}

is too close to

0.0

1.0

for the result to be computed. This will only occur when the large sample approximations are used.

11: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_ARRAY_SIZE: On entry, $array size = ⟨value⟩$ .
Constraint: $ldf1 > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $ldf2 > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $lp > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $ltail > 0$ .
NE_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NW_IVALID: On entry, at least one value of tail, p, df1, df2 was invalid, or the solution failed to converge.
Check ivalid for more information.

7 Accuracy

The result should be accurate to five significant digits.

8 Parallelism and Performance

Not applicable.

9 Further Comments

For higher accuracy nag_deviates_beta_vector (g01tec) can be used along with the transformations given in Section 3.

10 Example

This example reads the lower tail probabilities for several

F

-distributions, and calculates and prints the corresponding deviates.

NAG Library Function Documentnag_deviates_f_vector (g01tdc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_deviates_f_vector (g01tdc)