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_inv_cdf_normal_vector (g01ta)

## Purpose

nag_stat_inv_cdf_normal_vector (g01ta) returns a number of deviates associated with given probabilities of the Normal distribution.

## Syntax

[x, ivalid, ifail] = g01ta(tail, p, xmu, xstd, 'ltail', ltail, 'lp', lp, 'lxmu', lxmu, 'lxstd', lxstd)
[x, ivalid, ifail] = nag_stat_inv_cdf_normal_vector(tail, p, xmu, xstd, 'ltail', ltail, 'lp', lp, 'lxmu', lxmu, 'lxstd', lxstd)

## Description

The deviate, ${x}_{{p}_{i}}$ associated with the lower tail probability, ${p}_{i}$, for the Normal distribution is defined as the solution to
 $PXi≤xpi=pi=∫-∞xpiZiXidXi,$
where
 $ZiXi=12πσi2e-Xi-μi2/2σi2, ​-∞
The method used is an extension of that of Wichura (1988). ${p}_{i}$ is first replaced by ${q}_{i}={p}_{i}-0.5$.
(a) If $\left|{q}_{i}\right|\le 0.3$, ${z}_{i}$ is computed by a rational Chebyshev approximation
 $zi=siAisi2 Bisi2 ,$
where ${s}_{i}=\sqrt{2\pi }{q}_{i}$ and ${A}_{i}$, ${B}_{i}$ are polynomials of degree $7$.
(b) If $0.3<\left|{q}_{i}\right|\le 0.42$, ${z}_{i}$ is computed by a rational Chebyshev approximation
 $zi=sign⁡qi Citi Diti ,$
where ${t}_{i}=\left|{q}_{i}\right|-0.3$ and ${C}_{i}$, ${D}_{i}$ are polynomials of degree $5$.
(c) If $\left|{q}_{i}\right|>0.42$, ${z}_{i}$ is computed as
 $zi=sign⁡qi Eiui Fiui +ui ,$
where ${u}_{i}=\sqrt{-2×\mathrm{log}\left(\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({p}_{i},1-{p}_{i}\right)\right)}$ and ${E}_{i}$, ${F}_{i}$ are polynomials of degree $6$.
${x}_{{p}_{i}}$ is then calculated from ${z}_{i}$, using the relationsship ${z}_{{p}_{i}}=\frac{{x}_{i}-{\mu }_{i}}{{\sigma }_{i}}$.
For the upper tail probability $-{x}_{{p}_{i}}$ is returned, while for the two tail probabilities the value ${x}_{i{{p}_{i}}^{*}}$ is returned, where ${{p}_{i}}^{*}$ is the required tail probability computed from the input value of ${p}_{i}$.
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
Wichura (1988) Algorithm AS 241: the percentage points of the Normal distribution Appl. Statist. 37 477–484

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{tail}\left({\mathbf{ltail}}\right)$ – cell array of strings
Indicates which tail the supplied probabilities represent. Letting $Z$ denote a variate from a standard Normal distribution, and ${z}_{i}=\frac{{x}_{{p}_{i}}-{\mu }_{i}}{{\sigma }_{i}}$, then for , for $\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{lxmu}},{\mathbf{lxstd}}\right)$:
${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability, i.e., ${p}_{i}=P\left(Z\le {z}_{i}\right)$.
${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability, i.e., ${p}_{i}=P\left(Z\ge {z}_{i}\right)$.
${\mathbf{tail}}\left(j\right)=\text{'C'}$
The two tail (confidence interval) probability, i.e., ${p}_{i}=P\left(Z\le \left|{z}_{i}\right|\right)-P\left(Z\le -\left|{z}_{i}\right|\right)$.
${\mathbf{tail}}\left(j\right)=\text{'S'}$
The two tail (significance level) probability, i.e., ${p}_{i}=P\left(Z\ge \left|{z}_{i}\right|\right)+P\left(Z\le -\left|{z}_{i}\right|\right)$.
Constraint: ${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$, $\text{'U'}$, $\text{'C'}$ or $\text{'S'}$, for $\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     $\mathrm{p}\left({\mathbf{lp}}\right)$ – double array
${p}_{i}$, the probabilities for the Normal distribution as defined by tail with ${p}_{i}={\mathbf{p}}\left(j\right)$, .
Constraint: $0.0<{\mathbf{p}}\left(\mathit{j}\right)<1.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lp}}$.
3:     $\mathrm{xmu}\left({\mathbf{lxmu}}\right)$ – double array
${\mu }_{i}$, the means with ${\mu }_{i}={\mathbf{xmu}}\left(j\right)$, .
4:     $\mathrm{xstd}\left({\mathbf{lxstd}}\right)$ – double array
${\sigma }_{i}$, the standard deviations with ${\sigma }_{i}={\mathbf{xstd}}\left(j\right)$, .
Constraint: ${\mathbf{xstd}}\left(\mathit{j}\right)>0.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lxstd}}$.

### 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{lp}$int64int32nag_int scalar
Default: the dimension of the array p.
The length of the array p.
Constraint: ${\mathbf{lp}}>0$.
3:     $\mathrm{lxmu}$int64int32nag_int scalar
Default: the dimension of the array xmu.
The length of the array xmu.
Constraint: ${\mathbf{lxmu}}>0$.
4:     $\mathrm{lxstd}$int64int32nag_int scalar
Default: the dimension of the array xstd.
The length of the array xstd.
Constraint: ${\mathbf{lxstd}}>0$.

### Output Parameters

1:     $\mathrm{x}\left(:\right)$ – double array
The dimension of the array x will be $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}},{\mathbf{lp}}\right)$
${x}_{{p}_{i}}$, the deviates for the Normal 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{lxmu}},{\mathbf{lxstd}},{\mathbf{lp}}\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 ${x}_{{p}_{i}}$.
${\mathbf{ivalid}}\left(i\right)=2$
 On entry, ${p}_{i}\le 0.0$, or ${p}_{i}\ge 1.0$.
${\mathbf{ivalid}}\left(i\right)=3$
 On entry, ${\sigma }_{i}\le 0.0$.
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

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 tail, xstd or p was invalid.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{ltail}}>0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{lp}}>0$.
${\mathbf{ifail}}=4$
Constraint: ${\mathbf{lxmu}}>0$.
${\mathbf{ifail}}=5$
Constraint: ${\mathbf{lxstd}}>0$.
${\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 accuracy is mainly limited by the machine precision.

None.

## Example

This example reads vectors of values for ${\mu }_{i}$, ${\sigma }_{i}$ and ${p}_{i}$ and prints the corresponding deviates.
```function g01ta_example

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

p    = [0.9750; 0.0250; 0.9500; 0.0500];
xmu  = [0; 0; 0; 0];
xstd = [1; 1; 1; 1];
tail = {'L'; 'U'; 'C'; 'S'};

[dev, ivalid, ifail] = g01ta( ...
tail, p, xmu, xstd);

fprintf('tail    p              xmu      xstd      deviate\n');
lp    = numel(p);
lxmu  = numel(xmu);
lxstd = numel(xstd);
ltail = numel(tail);
len   = max ([lp, lxmu, lxstd, ltail]);
for i=0:len-1
fprintf(' %c%11.3f%16.4f%8.3f%13.6f\n', tail{mod(i,ltail)+1}, ...
p(mod(i,lp)+1), xmu(mod(i,lxmu)+1), xstd(mod(i,lxstd)+1), dev(i+1));
end

```
```g01ta example results

tail    p              xmu      xstd      deviate
L      0.975          0.0000   1.000     1.959964
U      0.025          0.0000   1.000     1.959964
C      0.950          0.0000   1.000     1.959964
S      0.050          0.0000   1.000     1.959964
```

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