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_noncentral_lincomb (g01jc)

## Purpose

nag_stat_prob_chisq_noncentral_lincomb (g01jc) returns the lower tail probability of a distribution of a positive linear combination of ${\chi }^{2}$ random variables.

## Syntax

[p, pdf, ifail] = g01jc(a, mult, rlamda, c, 'n', n, 'tol', tol, 'maxit', maxit)
[p, pdf, ifail] = nag_stat_prob_chisq_noncentral_lincomb(a, mult, rlamda, c, 'n', n, '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

For a linear combination of noncentral ${\chi }^{2}$ random variables with integer degrees of freedom the lower tail probability is
 $P ∑j=1najχ2mj,λj≤c ,$ (1)
where ${a}_{j}$ and $c$ are positive constants and where ${\chi }^{2}\left({m}_{j},{\lambda }_{j}\right)$ represents an independent ${\chi }^{2}$ random variable with ${m}_{j}$ degrees of freedom and noncentrality argument ${\lambda }_{j}$. The linear combination may arise from considering a quadratic form in Normal variables.
Ruben's method as described in Farebrother (1984) is used. Ruben has shown that (1) may be expanded as an infinite series of the form
 $∑k=0∞dkF m+2k,c/β ,$ (2)
where $F\left(m+2k,c/\beta \right)=P\left({\chi }^{2}\left(m+2k\right), i.e., the probability that a central ${\chi }^{2}$ is less than $c/\beta$.
The value of $\beta$ is set at
 $β=βB=21/amin+1/amax$
unless ${\beta }_{B}>1.8{a}_{\mathrm{min}}$, in which case
 $β=βA=amin$
is used, where ${a}_{\mathrm{min}}=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left\{{a}_{j}\right\}$ and ${a}_{\mathrm{max}}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left\{{a}_{j}\right\}$, for $\mathit{j}=1,2,\dots ,n$.

## References

Farebrother R W (1984) The distribution of a positive linear combination of ${\chi }^{2}$ random variables Appl. Statist. 33(3)

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{a}\left({\mathbf{n}}\right)$ – double array
The weights, ${a}_{1},{a}_{2},\dots ,{a}_{n}$.
Constraint: ${\mathbf{a}}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,n$.
2:     $\mathrm{mult}\left({\mathbf{n}}\right)$int64int32nag_int array
The degrees of freedom, ${m}_{1},{m}_{2},\dots ,{m}_{n}$.
Constraint: ${\mathbf{mult}}\left(\mathit{i}\right)\ge 1$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.
3:     $\mathrm{rlamda}\left({\mathbf{n}}\right)$ – double array
The noncentrality parameters, ${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$.
Constraint: ${\mathbf{rlamda}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$.
4:     $\mathrm{c}$ – double scalar
$c$, the point for which the lower tail probability is to be evaluated.
Constraint: ${\mathbf{c}}\ge 0.0$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the arrays a, mult, rlamda. (An error is raised if these dimensions are not equal.)
$n$, the number of ${\chi }^{2}$ random variables in the combination, i.e., the number of terms in equation (1).
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathrm{tol}$ – double scalar
Default: $0$
The relative accuracy required by you in the results. If nag_stat_prob_chisq_noncentral_lincomb (g01jc) 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.
3:     $\mathrm{maxit}$int64int32nag_int scalar
Default: $500$.
The maximum number of terms that should be used during the summation.
Constraint: ${\mathbf{maxit}}\ge 1$.

### Output Parameters

1:     $\mathrm{p}$ – double scalar
The lower tail probability associated with the linear combination of $n$ ${\chi }^{2}$ random variables with ${m}_{\mathit{j}}$ degrees of freedom, and noncentrality arguments ${\lambda }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$.
2:     $\mathrm{pdf}$ – double scalar
The value of the probability density function of the linear combination of ${\chi }^{2}$ variables.
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_noncentral_lincomb (g01jc) 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}}$ or ${\mathbf{2}}$, then nag_stat_prob_chisq_noncentral_lincomb (g01jc) returns $0.0$.

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

${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$, or ${\mathbf{maxit}}<1$, or ${\mathbf{c}}<0.0$.
${\mathbf{ifail}}=2$
 On entry, a has an element $\text{}\le 0.0$, or mult has an element $\text{}<1$, or rlamda has an element $\text{}<0.0$.
${\mathbf{ifail}}=3$
The central ${\chi }^{2}$ calculation has failed to converge. This is an unlikely exit. A larger value of tol should be tried.
W  ${\mathbf{ifail}}=4$
The solution has failed to converge within maxit iterations. A larger value of maxit or tol should be used. The returned value should be a reasonable approximation to the correct value.
W  ${\mathbf{ifail}}=5$
The solution appears to be too close to $0$ or $1$ for accurate calculation. The value returned is $0$ or $1$ as appropriate.
${\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 series (2) is summed until a bound on the truncation error is less than tol. See Farebrother (1984) for further discussion.

None.

## Example

The number of ${\chi }^{2}$ variables is read along with their coefficients, degrees of freedom and noncentrality arguments. The lower tail probability is then computed and printed.
```function g01jc_example

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

fprintf('        a     mult  rlamda\n');

% First set
a      = [        6   3  1];
mult   = [int64(1)  1  1];
rlamda = [        0   0  0];
c      = 20;

[p1, pdf, ifail] = g01jc( ...
a, mult, rlamda, c);

fprintf('%10.2f%6d%9.2f\n',[a; mult; rlamda]);
fprintf('c = %6.2f    prob = %6.4f\n\n', c, p1);

% Second set
a      = [        7   3];
mult   = [int64(1)  1];
rlamda = [        6   2];
c      = 10;

[p2, pdf, ifail] = g01jc( ...
a, mult, rlamda, c);

fprintf('%10.2f%6d%9.2f\n',[a; mult; rlamda]);
fprintf('c = %6.2f    prob = %6.4f\n', c, p2);

```
```g01jc example results

a     mult  rlamda
6.00     1     0.00
3.00     1     0.00
1.00     1     0.00
c =  20.00    prob = 0.8760

7.00     1     6.00
3.00     1     2.00
c =  10.00    prob = 0.0451
```