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 (g01ec)

## Purpose

nag_stat_prob_chisq (g01ec) returns the lower or upper tail probability for the ${\chi }^{2}$-distribution with real degrees of freedom.

## Syntax

[result, ifail] = g01ec(x, df, 'tail', tail)
[result, ifail] = nag_stat_prob_chisq(x, df, 'tail', tail)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: tail was made optional (default 'L')

## Description

The lower tail probability for the ${\chi }^{2}$-distribution with $\nu$ degrees of freedom, $P\left(X\le x:\nu \right)$ is defined by:
 $PX≤x:ν=12ν/2Γν/2 ∫0.0xXν/2-1e-X/2dX, x≥0,ν>0.$
To calculate $P\left(X\le x:\nu \right)$ a transformation of a gamma distribution is employed, i.e., a ${\chi }^{2}$-distribution with $\nu$ degrees of freedom is equal to a gamma distribution with scale parameter $2$ and shape parameter $\nu /2$.

## 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{x}$ – double scalar
$x$, the value of the ${\chi }^{2}$ variate with $\nu$ degrees of freedom.
Constraint: ${\mathbf{x}}\ge 0.0$.
2:     $\mathrm{df}$ – double scalar
$\nu$, the degrees of freedom of the ${\chi }^{2}$-distribution.
Constraint: ${\mathbf{df}}>0.0$.

### Optional Input Parameters

1:     $\mathrm{tail}$ – string (length ≥ 1)
Default: $\text{'L'}$
Indicates whether the upper or lower tail probability is required.
${\mathbf{tail}}=\text{'L'}$
The lower tail probability is returned, i.e., $P\left(X\le x:\nu \right)$.
${\mathbf{tail}}=\text{'U'}$
The upper tail probability is returned, i.e., $P\left(X\ge x:\nu \right)$.
Constraint: ${\mathbf{tail}}=\text{'L'}$ or $\text{'U'}$.

### Output Parameters

1:     $\mathrm{result}$ – double scalar
The result of the function.
2:     $\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 (g01ec) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
If ${\mathbf{ifail}}={\mathbf{1}}$, ${\mathbf{2}}$ or ${\mathbf{3}}$ on exit, then nag_stat_prob_chisq (g01ec) returns $0.0$.
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{tail}}\ne \text{'L'}$ or $\text{'U'}$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{x}}<0.0$.
${\mathbf{ifail}}=3$
 On entry, ${\mathbf{df}}\le 0.0$.
${\mathbf{ifail}}=4$
The solution has failed to converge while calculating the gamma variate. The result returned should represent an approximation to the solution.
${\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, until the end of data is reached.
```function g01ec_example

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

% Lower tail probabilities for Chi^2 distribution
x  = [ 8.26; 6.2; 55.76];
df = [20.00; 7.5; 45.00];
tail = {'Lower'; 'Lower'; 'Lower';};

fprintf('  Tail    x      df    probability\n');
for j = 1:numel(x);

[p, ifail] = g01ec( ...
x(j), df(j), 'tail', tail{j});

fprintf('%4s%8.3f%8.1f%12.4f\n',tail{j}(1), x(j), df(j), p);
end

```
```g01ec example results

Tail    x      df    probability
L   8.260    20.0      0.0100
L   6.200     7.5      0.4279
L  55.760    45.0      0.8694
```