Integer, Intent (In)	::	ltail, lp, ldf
Integer, Intent (Inout)	::	ifail
Integer, Intent (Out)	::	ivalid(*)
Real (Kind=nag_wp), Intent (In)	::	p(lp), df(ldf)
Real (Kind=nag_wp), Intent (Out)	::	x(*)
Character (1), Intent (In)	::	tail(ltail)

C Header Interface

#include <nag.h>

void	g01tcf_ (const Integer ltail, const char tail[], const Integer lp, const double p[], const Integer ldf, const double df[], double x[], Integer ivalid[], Integer ifail, const Charlen length_tail)

The routine may be called by the names g01tcf or nagf_stat_inv_cdf_chisq_vector.

3 Description

The deviate,

x_{p_{i}}

, associated with the lower tail probability

p_{i}

of the

χ^{2}

-distribution with

ν_{i}

degrees of freedom is defined as the solution to

P (X_{i} \leq x_{p_{i}} : ν_{i}) = p_{i} = \frac{1}{2^{ν_{i} / 2} Γ (ν_{i} / 2)} \int_{0}^{x_{p_{i}}} e^{- X_{i} / 2} {X_{i}}^{v_{i} / 2 - 1} d X_{i}, 0 \leq x_{p_{i}} < \infty; ​ ν_{i} > 0 .

The required

x_{p_{i}}

is found by using the relationship between a

χ^{2}

-distribution and a gamma distribution, i.e., a

χ^{2}

-distribution with

ν_{i}

degrees of freedom is equal to a gamma distribution with scale parameter

2

and shape parameter

ν_{i} / 2

For very large values of

ν_{i}

, greater than

10^{5}

, Wilson and Hilferty's Normal approximation to the

χ^{2}

is used; see Kendall and Stuart (1969).

The input arrays to this routine 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

Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the

χ^{2}

distribution Appl. Statist. 24 385–388

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

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

5 Arguments

1: $ltail$ – Integer Input

On entry: the length of the array tail.

Constraint:

ltail > 0

2: $tail (ltail)$ – Character(1) array Input

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

j = ((i - 1) mod ltail) + 1

, for

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

$tail (j) ='L'$: The lower tail probability, i.e., $p_{i} = P (X_{i} \leq x_{p_{i}} : ν_{i})$ .
$tail (j) ='U'$: The upper tail probability, i.e., $p_{i} = P (X_{i} \geq x_{p_{i}} : ν_{i})$ .

Constraint:

tail (j) ='L'

'U'

, for

j = 1, 2, \dots, ltail

3: $lp$ – Integer Input

On entry: the length of the array p.

Constraint:

lp > 0

4: $p (lp)$ – Real (Kind=nag_wp) array Input

On entry:

p_{i}

, the probability of the required

χ^{2}

-distribution as defined by tail with

p_{i} = p (j)

j = ((i - 1) mod lp) + 1

Constraints:

if $tail (k) ='L'$ , $0.0 \leq p (j) < 1.0$ ;
otherwise $0.0 < p (j) \leq 1.0$ .

Where

k = (i - 1) mod ltail + 1

and

j = (i - 1) mod lp + 1

5: $ldf$ – Integer Input

On entry: the length of the array df.

Constraint:

ldf > 0

6: $df (ldf)$ – Real (Kind=nag_wp) array Input

On entry:

ν_{i}

, the degrees of freedom of the

χ^{2}

-distribution with

ν_{i} = df (j)

j = ((i - 1) mod ldf) + 1

Constraint:

df (j) > 0.0

, for

j = 1, 2, \dots, ldf

7: $x (*)$ – Real (Kind=nag_wp) array Output

Note: the dimension of the array x must be at least

\max (ltail, lp, ldf)

On exit:

x_{p_{i}}

, the deviates for the

χ^{2}

-distribution.

8: $ivalid (*)$ – Integer array Output

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

\max (ltail, lp, ldf)

On exit:

ivalid (i)

indicates any errors with the input arguments, with

$ivalid (i) = 0$: No error.
$ivalid (i) = 1$: On entry, invalid value supplied in tail when calculating $x_{p_{i}}$ .
$ivalid (i) = 2$: On entry, invalid value for $p_{i}$ .
$ivalid (i) = 3$: On entry, $ν_{i} \leq 0.0$ .
$ivalid (i) = 4$: $p_{i}$ is too close to $0.0$ or $1.0$ for the result to be calculated.
$ivalid (i) = 5$: The solution has failed to converge. The result should be a reasonable approximation.

9: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

−1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

−1

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, at least one value of tail, p or df was invalid, or the solution failed to converge.
Check ivalid for more information.

$ifail = 2$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $ltail > 0$ .

$ifail = 3$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $lp > 0$ .

$ifail = 4$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $ldf > 0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The results should be accurate to five significant digits for most argument values. Some accuracy is lost for

p_{i}

close to

0.0

1.0

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

g01tcf is not threaded in any implementation.

9 Further Comments

For higher accuracy the relationship described in Section 3 may be used and a direct call to g01tff made.

10 Example

This example reads lower tail probabilities for several

χ^{2}

-distributions, and calculates and prints the corresponding deviates.

g01tc: FL CL CPP AD PY MB

NAG FL Interfaceg01tcf (inv_​cdf_​chisq_​vector)

▸▿ 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 FL Interface
g01tcf (inv_cdf_chisq_vector)