# NAG FL Interfaceg01taf (inv_​cdf_​normal_​vector)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g01taf returns a number of deviates associated with given probabilities of the Normal distribution.

## 2Specification

Fortran Interface
 Subroutine g01taf ( tail, lp, p, lxmu, xmu, xstd, x,
 Integer, Intent (In) :: ltail, lp, lxmu, lxstd Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: ivalid(*) Real (Kind=nag_wp), Intent (In) :: p(lp), xmu(lxmu), xstd(lxstd) Real (Kind=nag_wp), Intent (Out) :: x(*) Character (1), Intent (In) :: tail(ltail)
#include <nag.h>
 void g01taf_ (const Integer *ltail, const char tail[], const Integer *lp, const double p[], const Integer *lxmu, const double xmu[], const Integer *lxstd, const double xstd[], double x[], Integer ivalid[], Integer *ifail, const Charlen length_tail)
The routine may be called by the names g01taf or nagf_stat_inv_cdf_normal_vector.

## 3Description

The deviate, ${x}_{{p}_{i}}$ associated with the lower tail probability, ${p}_{i}$, for the Normal distribution is defined as the solution to
 $P(Xi≤xpi)=pi=∫-∞xpiZi(Xi)dXi,$
where
 $Zi(Xi)=12πσi2e-(Xi-μi)2/(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$.
1. (a)If $|{q}_{i}|\le 0.3$, ${z}_{i}$ is computed by a rational Chebyshev approximation
 $zi=siAi(si2) Bi(si2) ,$
where ${s}_{i}=\sqrt{2\pi }{q}_{i}$ and ${A}_{i}$, ${B}_{i}$ are polynomials of degree $7$.
2. (b)If $0.3<|{q}_{i}|\le 0.42$, ${z}_{i}$ is computed by a rational Chebyshev approximation
 $zi=sign⁡qi (Ci(ti) Di(ti) ) ,$
where ${t}_{i}=|{q}_{i}|-0.3$ and ${C}_{i}$, ${D}_{i}$ are polynomials of degree $5$.
3. (c)If $|{q}_{i}|>0.42$, ${z}_{i}$ is computed as
 $zi=sign⁡qi [(Ei(ui) Fi(ui) )+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 routine 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 Section 2.6 in the G01 Chapter Introduction for further information.

## 4References

NIST Digital Library of Mathematical Functions
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

## 5Arguments

1: $\mathbf{ltail}$Integer Input
On entry: the length of the array tail.
Constraint: ${\mathbf{ltail}}>0$.
2: $\mathbf{tail}\left({\mathbf{ltail}}\right)$Character(1) array Input
On entry: 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 |{z}_{i}|\right)-P\left(Z\le -|{z}_{i}|\right)$.
${\mathbf{tail}}\left(j\right)=\text{'S'}$
The two tail (significance level) probability, i.e., ${p}_{i}=P\left(Z\ge |{z}_{i}|\right)+P\left(Z\le -|{z}_{i}|\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}}$.
3: $\mathbf{lp}$Integer Input
On entry: the length of the array p.
Constraint: ${\mathbf{lp}}>0$.
4: $\mathbf{p}\left({\mathbf{lp}}\right)$Real (Kind=nag_wp) array Input
On entry: ${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}}$.
5: $\mathbf{lxmu}$Integer Input
On entry: the length of the array xmu.
Constraint: ${\mathbf{lxmu}}>0$.
6: $\mathbf{xmu}\left({\mathbf{lxmu}}\right)$Real (Kind=nag_wp) array Input
On entry: ${\mu }_{i}$, the means with ${\mu }_{i}={\mathbf{xmu}}\left(j\right)$, .
7: $\mathbf{lxstd}$Integer Input
On entry: the length of the array xstd.
Constraint: ${\mathbf{lxstd}}>0$.
8: $\mathbf{xstd}\left({\mathbf{lxstd}}\right)$Real (Kind=nag_wp) array Input
On entry: ${\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}}$.
9: $\mathbf{x}\left(*\right)$Real (Kind=nag_wp) array Output
Note: the dimension of the array x must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}},{\mathbf{lp}}\right)$.
On exit: ${x}_{{p}_{i}}$, the deviates for the Normal distribution.
10: $\mathbf{ivalid}\left(*\right)$Integer array Output
Note: the dimension of the array ivalid must be at least $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}},{\mathbf{lp}}\right)$.
On exit: ${\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$.
11: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, at least one value of tail, xstd or p was invalid.
${\mathbf{ifail}}=2$
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ltail}}>0$.
${\mathbf{ifail}}=3$
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{lp}}>0$.
${\mathbf{ifail}}=4$
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{lxmu}}>0$.
${\mathbf{ifail}}=5$
On entry, $\text{array size}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{lxstd}}>0$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

The accuracy is mainly limited by the machine precision.

## 8Parallelism and Performance

g01taf is not threaded in any implementation.

None.

## 10Example

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

### 10.1Program Text

Program Text (g01tafe.f90)

### 10.2Program Data

Program Data (g01tafe.d)

### 10.3Program Results

Program Results (g01tafe.r)