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

χ^{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: $tail (ltail)$ – cell array of strings

Indicates which tail the supplied probabilities represent. For

j = ((i - 1) mod ltail) + 1

, for

i = 1, 2, \dots, \max (ltail, lp, ldf)

$tail (j) ='L'$: The lower tail probability, i.e., $p_{i} = P (X_{i} \leq x_{p_{i}} : ν_{i})$ .
$tail (j) ='U'$: The upper tail probability, i.e., $p_{i} = P (X_{i} \geq x_{p_{i}} : ν_{i})$ .

Constraint:

tail (j) ='L'

'U'

, for

j = 1, 2, \dots, ltail

2: $p (lp)$ – double array

p_{i}

, the probability of the required

χ^{2}

-distribution as defined by tail with

p_{i} = p (j)

j = ((i - 1) mod lp) + 1

Constraints:

if $tail (k) ='L'$ , $0.0 \leq p (j) < 1.0$ ;
otherwise $0.0 < p (j) \leq 1.0$ .

Where

k = (i - 1) mod ltail + 1

and

j = (i - 1) mod lp + 1

3: $df (ldf)$ – double array

ν_{i}

, the degrees of freedom of the

χ^{2}

-distribution with

ν_{i} = df (j)

j = ((i - 1) mod ldf) + 1

Constraint:

df (j) > 0.0

, for

j = 1, 2, \dots, ldf

Optional Input Parameters

1: $ltail$ – int64int32nag_int scalar: Default: the dimension of the array tail.
The length of the array tail.

Constraint: $ltail > 0$ .
2: $lp$ – int64int32nag_int scalar: Default: the dimension of the array p.
The length of the array p.

Constraint: $lp > 0$ .
3: $ldf$ – int64int32nag_int scalar: Default: the dimension of the array df.
The length of the array df.

Constraint: $ldf > 0$ .

Output Parameters

1: $x (:)$ – double array

The dimension of the array x will be

\max (ltail, lp, ldf)

x_{p_{i}}

, the deviates for the

χ^{2}

-distribution.

2: $ivalid (:)$ – int64int32nag_int array

The dimension of the array ivalid will be

\max (ltail, lp, ldf)

ivalid (i)

indicates any errors with the input arguments, with

$ivalid (i) = 0$

No error.

$ivalid (i) = 1$

On entry,

invalid value supplied in tail when calculating

x_{p_{i}}

$ivalid (i) = 2$

On entry,

invalid value for

p_{i}

$ivalid (i) = 3$

On entry,

ν_{i} \leq 0.0

$ivalid (i) = 4$

p_{i}

is too close to

0.0

1.0

for the result to be calculated.

$ivalid (i) = 5$

The solution has failed to converge. The result should be a reasonable approximation.

3: $ifail$ – int64int32nag_int scalar

ifail = 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 $ifail = 1$: On entry, at least one value of tail, p or df was invalid, or the solution failed to converge.
Check ivalid for more information.

$ifail = 2$: Constraint: $ltail > 0$ .

$ifail = 3$: Constraint: $lp > 0$ .

$ifail = 4$: Constraint: $ldf > 0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$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

1.0

Further Comments

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

χ^{2}

-distributions, and calculates and prints the corresponding deviates.

Open in the MATLAB editor: g01tc_example

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

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox