Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_inv_cdf_chisq_vector (g01tc)

## Purpose

nag_stat_inv_cdf_chisq_vector (g01tc) returns a number of deviates associated with the given probabilities of the ${\chi }^{2}$-distribution with real degrees of freedom.

## Syntax

[x, ivalid, ifail] = g01tc(tail, p, df, 'ltail', ltail, 'lp', lp, 'ldf', ldf)
[x, ivalid, ifail] = nag_stat_inv_cdf_chisq_vector(tail, p, df, 'ltail', ltail, 'lp', lp, 'ldf', ldf)

## Description

The deviate, ${x}_{{p}_{i}}$, associated with the lower tail probability ${p}_{i}$ of the ${\chi }^{2}$-distribution with ${\nu }_{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 ${x}_{{p}_{i}}$ is found by using the relationship between a ${\chi }^{2}$-distribution and a gamma distribution, i.e., a ${\chi }^{2}$-distribution with ${\nu }_{i}$ degrees of freedom is equal to a gamma distribution with scale parameter $2$ and shape parameter ${\nu }_{i}/2$.
For very large values of ${\nu }_{i}$, greater than ${10}^{5}$, Wilson and Hilferty's Normal approximation to the ${\chi }^{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 Vectorized Routines in the G01 Chapter Introduction for further information.

## References

Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the ${\chi }^{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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{tail}\left({\mathbf{ltail}}\right)$ – cell array of strings
Indicates which tail the supplied probabilities represent. For , for $\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{ldf}}\right)$:
${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability, i.e., ${p}_{i}=P\left({X}_{i}\le {x}_{{p}_{i}}:{\nu }_{i}\right)$.
${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability, i.e., ${p}_{i}=P\left({X}_{i}\ge {x}_{{p}_{i}}:{\nu }_{i}\right)$.
Constraint: ${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$ or $\text{'U'}$, for $\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     $\mathrm{p}\left({\mathbf{lp}}\right)$ – double array
${p}_{i}$, the probability of the required ${\chi }^{2}$-distribution as defined by tail with ${p}_{i}={\mathbf{p}}\left(j\right)$, .
Constraints:
• if ${\mathbf{tail}}\left(k\right)=\text{'L'}$, $0.0\le {\mathbf{p}}\left(\mathit{j}\right)<1.0$;
• otherwise $0.0<{\mathbf{p}}\left(\mathit{j}\right)\le 1.0$.
Where  and .
3:     $\mathrm{df}\left({\mathbf{ldf}}\right)$ – double array
${\nu }_{i}$, the degrees of freedom of the ${\chi }^{2}$-distribution with ${\nu }_{i}={\mathbf{df}}\left(j\right)$, .
Constraint: ${\mathbf{df}}\left(\mathit{j}\right)>0.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{ldf}}$.

### Optional Input Parameters

1:     $\mathrm{ltail}$int64int32nag_int scalar
Default: the dimension of the array tail.
The length of the array tail.
Constraint: ${\mathbf{ltail}}>0$.
2:     $\mathrm{lp}$int64int32nag_int scalar
Default: the dimension of the array p.
The length of the array p.
Constraint: ${\mathbf{lp}}>0$.
3:     $\mathrm{ldf}$int64int32nag_int scalar
Default: the dimension of the array df.
The length of the array df.
Constraint: ${\mathbf{ldf}}>0$.

### Output Parameters

1:     $\mathrm{x}\left(:\right)$ – double array
The dimension of the array x will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{ldf}}\right)$
${x}_{{p}_{i}}$, the deviates for the ${\chi }^{2}$-distribution.
2:     $\mathrm{ivalid}\left(:\right)$int64int32nag_int array
The dimension of the array ivalid will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{ldf}}\right)$
${\mathbf{ivalid}}\left(i\right)$ indicates any errors with the input arguments, with
${\mathbf{ivalid}}\left(i\right)=0$
No error.
${\mathbf{ivalid}}\left(i\right)=1$
 On entry, invalid value supplied in tail when calculating ${x}_{{p}_{i}}$.
${\mathbf{ivalid}}\left(i\right)=2$
 On entry, invalid value for ${p}_{i}$.
${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ${\nu }_{i}\le 0.0$.
${\mathbf{ivalid}}\left(i\right)=4$
${p}_{i}$ is too close to $0.0$ or $1.0$ for the result to be calculated.
${\mathbf{ivalid}}\left(i\right)=5$
The solution has failed to converge. The result should be a reasonable approximation.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W  ${\mathbf{ifail}}=1$
On entry, at least one value of tail, p or df was invalid, or the solution failed to converge.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{ltail}}>0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{lp}}>0$.
${\mathbf{ifail}}=4$
Constraint: ${\mathbf{ldf}}>0$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## 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$ or $1.0$.

For higher accuracy the relationship described in Description may be used and a direct call to nag_stat_inv_cdf_gamma_vector (g01tf) made.

## Example

This example reads lower tail probabilities for several ${\chi }^{2}$-distributions, and calculates and prints the corresponding deviates.
```function g01tc_example

fprintf('g01tc example results\n\n');

tail = {'L'};
p    = [0.01; 0.428; 0.869];
df   = [20;   7.5;  45];
[x, ivalid, ifail] = g01tc( ...
tail, p, df);

fprintf('  tail     p       df      x     ivalid\n');
ltail = numel(tail);
lp    = numel(p);
ldf   = numel(df);
len   = max ([ltail, lp, ldf]);
for i=0:len-1
fprintf('%5s%8.3f%8.3f%8.3f%8d\n',  tail{mod(i, ltail)+1}, ...
p(mod(i,lp)+1), df(mod(i,ldf)+1), x(i+1), ivalid(i+1));
end

```
```g01tc example results

tail     p       df      x     ivalid
L   0.010  20.000   8.260       0
L   0.428   7.500   6.201       0
L   0.869  45.000  55.738       0
```