nag_deviates_normal_vector (g01tac) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual

NAG Library Function Documentnag_deviates_normal_vector (g01tac)

1  Purpose

nag_deviates_normal_vector (g01tac) returns a number of deviates associated with given probabilities of the Normal distribution.

2  Specification

 #include #include
 void nag_deviates_normal_vector (Integer ltail, const Nag_TailProbability tail[], Integer lp, const double p[], Integer lxmu, const double xmu[], Integer lxstd, const double xstd[], double x[], Integer ivalid[], NagError *fail)

3  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 Section 2.6 in the g01 Chapter Introduction for further information.

4  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

5  Arguments

1:     ltailIntegerInput
On entry: the length of the array tail.
Constraint: ${\mathbf{ltail}}>0$.
2:     tail[${\mathbf{ltail}}$]const Nag_TailProbabilityInput
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]=\mathrm{Nag_LowerTail}$
The lower tail probability, i.e., ${p}_{i}=P\left(Z\le {z}_{i}\right)$.
${\mathbf{tail}}\left[j\right]=\mathrm{Nag_UpperTail}$
The upper tail probability, i.e., ${p}_{i}=P\left(Z\ge {z}_{i}\right)$.
${\mathbf{tail}}\left[j\right]=\mathrm{Nag_TwoTailConfid}$
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]=\mathrm{Nag_TwoTailSignif}$
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}-1\right]=\mathrm{Nag_LowerTail}$, $\mathrm{Nag_UpperTail}$, $\mathrm{Nag_TwoTailConfid}$ or $\mathrm{Nag_TwoTailSignif}$, for $\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
3:     lpIntegerInput
On entry: the length of the array p.
Constraint: ${\mathbf{lp}}>0$.
4:     p[lp]const doubleInput
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}-1\right]<1.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lp}}$.
5:     lxmuIntegerInput
On entry: the length of the array xmu.
Constraint: ${\mathbf{lxmu}}>0$.
6:     xmu[lxmu]const doubleInput
On entry: ${\mu }_{i}$, the means with ${\mu }_{i}={\mathbf{xmu}}\left[j\right]$, .
7:     lxstdIntegerInput
On entry: the length of the array xstd.
Constraint: ${\mathbf{lxstd}}>0$.
8:     xstd[lxstd]const doubleInput
On entry: ${\sigma }_{i}$, the standard deviations with ${\sigma }_{i}={\mathbf{xstd}}\left[j\right]$, .
Constraint: ${\mathbf{xstd}}\left[\mathit{j}-1\right]>0.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{lxstd}}$.
9:     x[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, 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:   ivalid[$\mathit{dim}$]IntegerOutput
Note: the dimension, dim, 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-1\right]$ indicates any errors with the input arguments, with
${\mathbf{ivalid}}\left[i-1\right]=0$
No error.
${\mathbf{ivalid}}\left[i-1\right]=1$
 On entry, invalid value supplied in tail when calculating ${x}_{{p}_{i}}$.
${\mathbf{ivalid}}\left[i-1\right]=2$
 On entry, ${p}_{i}\le 0.0$, or ${p}_{i}\ge 1.0$.
${\mathbf{ivalid}}\left[i-1\right]=3$
 On entry, ${\sigma }_{i}\le 0.0$.
11:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_ARRAY_SIZE
On entry, $\text{array size}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{lp}}>0$.
On entry, $\text{array size}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ltail}}>0$.
On entry, $\text{array size}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{lxmu}}>0$.
On entry, $\text{array size}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{lxstd}}>0$.
NE_BAD_PARAM
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NW_IVALID
On entry, at least one value of tail, xstd or p was invalid.
Check ivalid for more information.

7  Accuracy

The accuracy is mainly limited by the machine precision.

None.

9  Example

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

9.1  Program Text

Program Text (g01tace.c)

9.2  Program Data

Program Data (g01tace.d)

9.3  Program Results

Program Results (g01tace.r)

nag_deviates_normal_vector (g01tac) (PDF version)
g01 Chapter Contents
g01 Chapter Introduction
NAG C Library Manual