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

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_stat_prob_chisq_noncentral (g01gc)

## Purpose

nag_stat_prob_chisq_noncentral (g01gc) returns the probability associated with the lower tail of the noncentral ${\chi }^{2}$-distribution via the function name.

## Syntax

[result, ifail] = g01gc(x, df, rlamda, 'tol', tol, 'maxit', maxit)
[result, ifail] = nag_stat_prob_chisq_noncentral(x, df, rlamda, 'tol', tol, 'maxit', maxit)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: tol was made optional (default 0)

## Description

The lower tail probability of the noncentral ${\chi }^{2}$-distribution with $\nu$ degrees of freedom and noncentrality parameter $\lambda$, $P\left(X\le x:\nu \text{;}\lambda \right)$, is defined by
 $PX≤x:ν;λ=∑j=0∞e-λ/2λ/2jj! PX≤x:ν+2j;0,$ (1)
where $P\left(X\le x:\nu +2j\text{;}0\right)$ is a central ${\chi }^{2}$-distribution with $\nu +2j$ degrees of freedom.
The value of $j$ at which the Poisson weight, ${e}^{-\lambda /2}\frac{{\left(\lambda /2\right)}^{j}}{j!}$, is greatest is determined and the summation (1) is made forward and backward from that value of $j$.
The recursive relationship:
 $PX≤x:a+2;0=PX≤x:a;0-xa/2e-x/2 Γa+1$ (2)
is used during the summation in (1).

## References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}$ – double scalar
The deviate from the noncentral ${\chi }^{2}$-distribution with $\nu$ degrees of freedom and noncentrality parameter $\lambda$.
Constraint: ${\mathbf{x}}\ge 0.0$.
2:     $\mathrm{df}$ – double scalar
$\nu$, the degrees of freedom of the noncentral ${\chi }^{2}$-distribution.
Constraint: ${\mathbf{df}}\ge 0.0$.
3:     $\mathrm{rlamda}$ – double scalar
$\lambda$, the noncentrality parameter of the noncentral ${\chi }^{2}$-distribution.
Constraint: ${\mathbf{rlamda}}\ge 0.0$ if ${\mathbf{df}}>0.0$ or ${\mathbf{rlamda}}>0.0$ if ${\mathbf{df}}=0.0$.

### Optional Input Parameters

1:     $\mathrm{tol}$ – double scalar
Default: $0.0$
The required accuracy of the solution. If nag_stat_prob_chisq_noncentral (g01gc) is entered with tol greater than or equal to $1.0$ or less than  (see nag_machine_precision (x02aj)), then the value of  is used instead.
2:     $\mathrm{maxit}$int64int32nag_int scalar
Default: $100$. See Further Comments for further discussion.
The maximum number of iterations to be performed.
Constraint: ${\mathbf{maxit}}\ge 1$.

### 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_noncentral (g01gc) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:
If on exit ${\mathbf{ifail}}={\mathbf{1}}$, ${\mathbf{2}}$, ${\mathbf{4}}$ or ${\mathbf{5}}$, then nag_stat_prob_chisq_noncentral (g01gc) returns $0.0$.
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{df}}<0.0$, or ${\mathbf{rlamda}}<0.0$, or ${\mathbf{df}}=0.0$ and ${\mathbf{rlamda}}=0.0$, or ${\mathbf{x}}<0.0$, or ${\mathbf{maxit}}<1$.
${\mathbf{ifail}}=2$
The initial value of the Poisson weight used in the summation (1) was too small to be calculated. The value of $P\left({\mathbf{x}}\le x:\nu \text{;}\lambda \right)$ is likely to be zero.
${\mathbf{ifail}}=3$
The solution has failed to converge in maxit iterations.
${\mathbf{ifail}}=4$
The value of a term required in (2) is too large to be evaluated accurately. The most likely cause of this error is both x and rlamda being very large.
${\mathbf{ifail}}=5$
The calculations for the central ${\chi }^{2}$ probability has failed to converge. This is an unlikely error exit. A larger value of tol should be used.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
${\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 summations described in Description are made until an upper bound on the truncation error relative to the current summation value is less than tol.

## Further Comments

The number of terms in (1) required for a given accuracy will depend on the following factors:
 (i) The rate at which the Poisson weights tend to zero. This will be slower for larger values of $\lambda$. (ii) The rate at which the central ${\chi }^{2}$ probabilities tend to zero. This will be slower for larger values of $\nu$ and $x$.

## Example

This example reads values from various noncentral ${\chi }^{2}$-distributions, calculates the lower tail probabilities and prints all these values until the end of data is reached.
```function g01gc_example

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

x      = [  8.26   6.2   55.76];
df     = [ 20      7.5   45   ];
rlamda = [  3.5    2      1   ];
p      = x;

fprintf('     x       df   rlamda     p\n');
for j = 1:numel(x)
[p(j), ifail] = g01gc( ...
x(j), df(j), rlamda(j));
end

fprintf('%8.3f%8.3f%8.3f%8.4f\n', [x; df; rlamda; p]);

```
```g01gc example results

x       df   rlamda     p
8.260  20.000   3.500  0.0032
6.200   7.500   2.000  0.2699
55.760  45.000   1.000  0.8443
```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015