nag_deviates_chi_sq_vector (g01tcc) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_deviates_chi_sq_vector (g01tcc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_deviates_chi_sq_vector (g01tcc) returns a number of deviates associated with the given probabilities of the χ2-distribution with real degrees of freedom.

2  Specification

#include <nag.h>
#include <nagg01.h>
void  nag_deviates_chi_sq_vector (Integer ltail, const Nag_TailProbability tail[], Integer lp, const double p[], Integer ldf, const double df[], double x[], Integer ivalid[], NagError *fail)

3  Description

The deviate, xpi, associated with the lower tail probability pi of the χ2-distribution with νi degrees of freedom is defined as the solution to
P Xi xpi :νi = pi = 1 2 νi/2 Γ νi/2 0 xpi e -Xi/2 Xi vi / 2 - 1 dXi ,   0 xpi < ; ​ νi > 0 .
The required xpi 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 105, Wilson and Hilferty's Normal approximation to the χ2 is used; see Kendall and Stuart (1969).
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

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:     ltailIntegerInput
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,,maxltail,lp,ldf:
tail[j]=Nag_LowerTail
The lower tail probability, i.e., pi = P Xi xpi :νi .
tail[j]=Nag_UpperTail
The upper tail probability, i.e., pi = P Xi xpi :νi .
Constraint: tail[j-1]=Nag_LowerTail or Nag_UpperTail, for j=1,2,,ltail.
3:     lpIntegerInput
On entry: the length of the array p.
Constraint: lp>0.
4:     p[lp]const doubleInput
On entry: pi, the probability of the required χ2-distribution as defined by tail with pi=p[j], j=i-1 mod lp.
Constraints:
  • if tail[k]=Nag_LowerTail, 0.0p[j]<1.0;
  • otherwise 0.0<p[j]1.0.
Where k=i-1 mod ltail and j=i-1 mod lp.
5:     ldfIntegerInput
On entry: the length of the array df.
Constraint: ldf>0.
6:     df[ldf]const doubleInput
On entry: νi, the degrees of freedom of the χ2-distribution with νi=df[j], j=i-1 mod ldf.
Constraint: df[j-1]>0.0, for j=1,2,,ldf.
7:     x[dim]doubleOutput
Note: the dimension, dim, of the array x must be at least maxltail,lp,ldf.
On exit: xpi, the deviates for the χ2-distribution.
8:     ivalid[dim]IntegerOutput
Note: the dimension, dim, of the array ivalid must be at least maxltail,lp,ldf.
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 xpi.
ivalid[i-1]=2
On entry,invalid value for pi.
ivalid[i-1]=3
On entry,νi0.0.
ivalid[i-1]=4
pi is too close to 0.0 or 1.0 for the result to be calculated.
ivalid[i-1]=5
The solution has failed to converge. The result should be a reasonable approximation.
9:     failNagError *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: ldf>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 or df was invalid, or the solution failed to converge.
Check ivalid for more information.

7  Accuracy

The results should be accurate to five significant digits for most argument values. Some accuracy is lost for pi close to 0.0 or 1.0.

8  Further Comments

For higher accuracy the relationship described in Section 3 may be used and a direct call to nag_deviates_gamma_vector (g01tfc) made.

9  Example

This example reads lower tail probabilities for several χ2-distributions, and calculates and prints the corresponding deviates.

9.1  Program Text

Program Text (g01tcce.c)

9.2  Program Data

Program Data (g01tcce.d)

9.3  Program Results

Program Results (g01tcce.r)


nag_deviates_chi_sq_vector (g01tcc) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012