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_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, xpi${x}_{{p}_{i}}$ associated with the lower tail probability, pi${p}_{i}$, for the Normal distribution is defined as the solution to
 xpi P(Xi ≤ xpi) = pi = ∫ Zi(Xi)dXi, − ∞
$P(Xi≤xpi)=pi=∫-∞xpiZi(Xi)dXi,$
where
 Zi(Xi) = 1/(sqrt(2πσi2))e − (Xi − μi)2 / (2σi2), ​ − ∞ < Xi < ∞. $Zi(Xi)=12πσi2e-(Xi-μi)2/(2σi2), ​-∞
The method used is an extension of that of Wichura (1988). pi${p}_{i}$ is first replaced by qi = pi0.5${q}_{i}={p}_{i}-0.5$.
(a) If |qi|0.3$|{q}_{i}|\le 0.3$, zi${z}_{i}$ is computed by a rational Chebyshev approximation
 zi = si(Ai(si2))/(Bi(si2)), $zi=siAi(si2) Bi(si2) ,$
where si = sqrt(2π)qi${s}_{i}=\sqrt{2\pi }{q}_{i}$ and Ai${A}_{i}$, Bi${B}_{i}$ are polynomials of degree 7$7$.
(b) If 0.3 < |qi|0.42$0.3<|{q}_{i}|\le 0.42$, zi${z}_{i}$ is computed by a rational Chebyshev approximation
 zi = signqi ((Ci(ti))/(Di(ti))) , $zi=sign⁡qi (Ci(ti) Di(ti) ) ,$
where ti = |qi|0.3${t}_{i}=|{q}_{i}|-0.3$ and Ci${C}_{i}$, Di${D}_{i}$ are polynomials of degree 5$5$.
(c) If |qi| > 0.42$|{q}_{i}|>0.42$, zi${z}_{i}$ is computed as
 zi = signqi [((Ei(ui))/(Fi(ui))) + ui] , $zi=sign⁡qi [ (Ei(ui) Fi(ui) )+ui] ,$
where ui = sqrt( 2 × log(min (pi,1pi)) ) ${u}_{i}=\sqrt{-2×\mathrm{log}\left(\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({p}_{i},1-{p}_{i}\right)\right)}$ and Ei${E}_{i}$, Fi${F}_{i}$ are polynomials of degree 6$6$.
xpi${x}_{{p}_{i}}$ is then calculated from zi${z}_{i}$, using the relationsship zpi = ( xi μi )/(σi) ${z}_{{p}_{i}}=\frac{{x}_{i}-{\mu }_{i}}{{\sigma }_{i}}$.
For the upper tail probability xpi$-{x}_{{p}_{i}}$ is returned, while for the two tail probabilities the value xipi*${x}_{i{{p}_{i}}^{*}}$ is returned, where pi*${{p}_{i}}^{*}$ is the required tail probability computed from the input value of pi${p}_{i}$.
The input arrays to this function are designed to allow maximum flexibility in the supply of vector parameters by re-using elements of any arrays that are shorter than the total number of evaluations required. See Section [Vectorized s] 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:     tail(ltail) – cell array of strings
ltail, the dimension of the array, must satisfy the constraint ltail > 0${\mathbf{ltail}}>0$.
Indicates which tail the supplied probabilities represent. Letting Z$Z$ denote a variate from a standard Normal distribution, and zi = ( xpi μi )/(σi)${z}_{i}=\frac{{x}_{{p}_{i}}-{\mu }_{i}}{{\sigma }_{i}}$, then for j = ((i1)  mod  ltail) + 1 , for i = 1,2,,max (ltail,lp,lxmu,lxstd)$\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lp}},{\mathbf{lxmu}},{\mathbf{lxstd}}\right)$:
tail(j) = 'L'${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability, i.e., pi = P(Zzi)${p}_{i}=P\left(Z\le {z}_{i}\right)$.
tail(j) = 'U'${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability, i.e., pi = P(Zzi)${p}_{i}=P\left(Z\ge {z}_{i}\right)$.
tail(j) = 'C'${\mathbf{tail}}\left(j\right)=\text{'C'}$
The two tail (confidence interval) probability, i.e., pi = P(Z|zi|)P(Z|zi|)${p}_{i}=P\left(Z\le |{z}_{i}|\right)-P\left(Z\le -|{z}_{i}|\right)$.
tail(j) = 'S'${\mathbf{tail}}\left(j\right)=\text{'S'}$
The two tail (significance level) probability, i.e., pi = P(Z|zi|) + P(Z|zi|)${p}_{i}=P\left(Z\ge |{z}_{i}|\right)+P\left(Z\le -|{z}_{i}|\right)$.
Constraint: tail(j) = 'L'${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$, 'U'$\text{'U'}$, 'C'$\text{'C'}$ or 'S'$\text{'S'}$, for j = 1,2,,ltail$\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     p(lp) – double array
lp, the dimension of the array, must satisfy the constraint lp > 0${\mathbf{lp}}>0$.
pi${p}_{i}$, the probabilities for the Normal distribution as defined by tail with pi = p(j)${p}_{i}={\mathbf{p}}\left(j\right)$, j = (i1)  mod  lp + 1.
Constraint: 0.0 < p(j) < 1.0$0.0<{\mathbf{p}}\left(\mathit{j}\right)<1.0$, for j = 1,2,,lp$\mathit{j}=1,2,\dots ,{\mathbf{lp}}$.
3:     xmu(lxmu) – double array
lxmu, the dimension of the array, must satisfy the constraint lxmu > 0${\mathbf{lxmu}}>0$.
μi${\mu }_{i}$, the means with μi = xmu(j)${\mu }_{i}={\mathbf{xmu}}\left(j\right)$, j = ((i1)  mod  lxmu) + 1.
4:     xstd(lxstd) – double array
lxstd, the dimension of the array, must satisfy the constraint lxstd > 0${\mathbf{lxstd}}>0$.
σi${\sigma }_{i}$, the standard deviations with σi = xstd(j)${\sigma }_{i}={\mathbf{xstd}}\left(j\right)$, j = ((i1)  mod  lxstd) + 1.
Constraint: xstd(j) > 0.0${\mathbf{xstd}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,lxstd$\mathit{j}=1,2,\dots ,{\mathbf{lxstd}}$.

### Optional Input Parameters

1:     ltail – int64int32nag_int scalar
Default: The dimension of the array tail.
The length of the array tail.
Constraint: ltail > 0${\mathbf{ltail}}>0$.
2:     lp – int64int32nag_int scalar
Default: The dimension of the array p.
The length of the array p.
Constraint: lp > 0${\mathbf{lp}}>0$.
3:     lxmu – int64int32nag_int scalar
Default: The dimension of the array xmu.
The length of the array xmu.
Constraint: lxmu > 0${\mathbf{lxmu}}>0$.
4:     lxstd – int64int32nag_int scalar
Default: The dimension of the array xstd.
The length of the array xstd.
Constraint: lxstd > 0${\mathbf{lxstd}}>0$.

None.

### Output Parameters

1:     x( : $:$) – double array
Note: the dimension of the array x must be at least max (ltail,lxmu,lxstd,lp)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}},{\mathbf{lp}}\right)$.
xpi${x}_{{p}_{i}}$, the deviates for the Normal distribution.
2:     ivalid( : $:$) – int64int32nag_int array
Note: the dimension of the array ivalid must be at least max (ltail,lxmu,lxstd,lp)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}},{\mathbf{lp}}\right)$.
ivalid(i)${\mathbf{ivalid}}\left(i\right)$ indicates any errors with the input arguments, with
ivalid(i) = 0${\mathbf{ivalid}}\left(i\right)=0$
No error.
ivalid(i) = 1${\mathbf{ivalid}}\left(i\right)=1$
 On entry, invalid value supplied in tail when calculating xpi${x}_{{p}_{i}}$.
ivalid(i) = 2${\mathbf{ivalid}}\left(i\right)=2$
 On entry, pi ≤ 0.0${p}_{i}\le 0.0$, or pi ≥ 1.0${p}_{i}\ge 1.0$.
ivalid(i) = 3${\mathbf{ivalid}}\left(i\right)=3$
 On entry, σi ≤ 0.0${\sigma }_{i}\le 0.0$.
3:     ifail – int64int32nag_int scalar
${\mathrm{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 ifail = 1${\mathbf{ifail}}=1$
On entry, at least one value of tail, xstd or p was invalid.
ifail = 2${\mathbf{ifail}}=2$
Constraint: ltail > 0${\mathbf{ltail}}>0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: lp > 0${\mathbf{lp}}>0$.
ifail = 4${\mathbf{ifail}}=4$
Constraint: lxmu > 0${\mathbf{lxmu}}>0$.
ifail = 5${\mathbf{ifail}}=5$
Constraint: lxstd > 0${\mathbf{lxstd}}>0$.
ifail = 999${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The accuracy is mainly limited by the machine precision.

None.

## Example

```function nag_stat_inv_cdf_normal_vector_example
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] = nag_stat_inv_cdf_normal_vector(tail, p, xmu, xstd);

fprintf('\nTail    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%11d\n', tail{mod(i,ltail)+1}, p(mod(i,lp)+1), ...
xmu(mod(i,lxmu)+1), xstd(mod(i,lxstd)+1), dev(i+1),  ivalid(i+1));
end
```
```

Tail    P              XMU      XSTD      Deviate
L      0.975          0.0000   1.000     1.959964          0
U      0.025          0.0000   1.000     1.959964          0
C      0.950          0.0000   1.000     1.959964          0
S      0.050          0.0000   1.000     1.959964          0

```
```function g01ta_example
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('\nTail    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%11d\n', tail{mod(i,ltail)+1}, p(mod(i,lp)+1), ...
xmu(mod(i,lxmu)+1), xstd(mod(i,lxstd)+1), dev(i+1),  ivalid(i+1));
end
```
```

Tail    P              XMU      XSTD      Deviate
L      0.975          0.0000   1.000     1.959964          0
U      0.025          0.0000   1.000     1.959964          0
C      0.950          0.0000   1.000     1.959964          0
S      0.050          0.0000   1.000     1.959964          0

```