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_prob_chisq_vector (g01sc)

## Purpose

nag_stat_prob_chisq_vector (g01sc) returns a number of lower or upper tail probabilities for the ${\chi }^{2}$-distribution with real degrees of freedom.

## Syntax

[p, ivalid, ifail] = g01sc(tail, x, df, 'ltail', ltail, 'lx', lx, 'ldf', ldf)
[p, ivalid, ifail] = nag_stat_prob_chisq_vector(tail, x, df, 'ltail', ltail, 'lx', lx, 'ldf', ldf)

## Description

The lower tail probability for the ${\chi }^{2}$-distribution with ${\nu }_{i}$ degrees of freedom, $P=\left({X}_{i}\le {x}_{i}:{\nu }_{i}\right)$ is defined by:
 $P = Xi≤xi:νi = 1 2 νi/2 Γ νi/2 ∫ 0.0 xi Xi νi/2-1 e -Xi/2 dXi , xi ≥ 0 , νi > 0 .$
To calculate $P=\left({X}_{i}\le {x}_{i}:{\nu }_{i}\right)$ a transformation of a gamma distribution is employed, 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$.
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

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{tail}\left({\mathbf{ltail}}\right)$ – cell array of strings
Indicates whether the lower or upper tail probabilities are required. For , for $\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lx}},{\mathbf{ldf}}\right)$:
${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability is returned, i.e., ${p}_{i}=P\left({X}_{i}\le {x}_{i}:{\nu }_{i}\right)$.
${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability is returned, i.e., ${p}_{i}=P\left({X}_{i}\ge {x}_{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{x}\left({\mathbf{lx}}\right)$ – double array
${x}_{i}$, the values of the ${\chi }^{2}$ variates with ${\nu }_{i}$ degrees of freedom with ${x}_{i}={\mathbf{x}}\left(j\right)$, .
Constraint: ${\mathbf{x}}\left(\mathit{j}\right)\ge 0.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lx}}$.
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{lx}$int64int32nag_int scalar
Default: the dimension of the array x.
The length of the array x.
Constraint: ${\mathbf{lx}}>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{p}\left(:\right)$ – double array
The dimension of the array p will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{ldf}},{\mathbf{lx}}\right)$
${p}_{i}$, the probabilities 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{ldf}},{\mathbf{lx}}\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 ${p}_{i}$.
${\mathbf{ivalid}}\left(i\right)=2$
 On entry, ${x}_{i}<0.0$.
${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ${\nu }_{i}\le 0.0$.
${\mathbf{ivalid}}\left(i\right)=4$
The solution has failed to converge while calculating the gamma variate. The result returned should represent an approximation to the solution.
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

Note: nag_stat_prob_chisq_vector (g01sc) may return useful information for one or more of the following detected errors or 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 x, df or tail was invalid, or the solution failed to converge.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{ltail}}>0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{lx}}>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

A relative accuracy of five significant figures is obtained in most cases.

For higher accuracy the transformation described in Description may be used with a direct call to nag_specfun_gamma_incomplete (s14ba).

## Example

Values from various ${\chi }^{2}$-distributions are read, the lower tail probabilities calculated, and all these values printed out.
```function g01sc_example

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

x = [8.26; 6.2; 55.76];
df = [20; 7.5; 45];
tail = {'L'};
% calculate probability
[prob, ivalid, ifail] = g01sc( ...
tail, x, df);

fprintf('    x      df     prob\n');
lx    = numel(x);
ldf   = numel(df);
ltail = numel(tail);
len   = max ([lx, ldf, ltail]);
for i=0:len-1
fprintf('%7.3f%8.3f%8.3f\n', x(mod(i,lx)+1), df(mod(i,ldf)+1), prob(i+1));
end

```
```g01sc example results

x      df     prob
8.260  20.000   0.010
6.200   7.500   0.428
55.760  45.000   0.869
```