NAG Library Function Document

nag_deviates_normal_vector (g01tac)

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

P (X_{i} \leq x_{p_{i}}) = p_{i} = \int_{- \infty}^{x_{p_{i}}} Z_{i} (X_{i}) d X_{i},

where

Z_{i} (X_{i}) = \frac{1}{\sqrt{2 π {σ_{i}}^{2}}} e^{- {(X_{i} - μ_{i})}^{2} / (2 {σ_{i}}^{2})}, ​ - \infty < X_{i} < \infty .

The method used is an extension of that of Wichura (1988).

p_{i}

is first replaced by

q_{i} = p_{i} - 0.5

(a)

|q_{i}| \leq 0.3

z_{i}

is computed by a rational Chebyshev approximation

z_{i} = s_{i} \frac{A_{i} ({s_{i}}^{2})}{B_{i} ({s_{i}}^{2})},

where

s_{i} = \sqrt{2 π} q_{i}

and

A_{i}

B_{i}

are polynomials of degree

7

(b)

0.3 < |q_{i}| \leq 0.42

z_{i}

is computed by a rational Chebyshev approximation

z_{i} = sign q_{i} (\frac{C_{i} (t_{i})}{D_{i} (t_{i})}),

where

t_{i} = |q_{i}| - 0.3

and

C_{i}

D_{i}

are polynomials of degree

5

(c)

|q_{i}| > 0.42

z_{i}

is computed as

z_{i} = sign q_{i} [(\frac{E_{i} (u_{i})}{F_{i} (u_{i})}) + u_{i}],

where

u_{i} = \sqrt{- 2 \times \log (\min (p_{i}, 1 - p_{i}))}

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} - μ_{i}}{σ_{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: ltail – IntegerInput

On entry: the length of the array tail.

Constraint:

ltail > 0

2: tail[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}} - μ_{i}}{σ_{i}}

, then for

j = (i - 1) mod ltail

, for

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

$tail [j] = Nag_LowerTail$: The lower tail probability, i.e., $p_{i} = P (Z \leq z_{i})$ .
$tail [j] = Nag_UpperTail$: The upper tail probability, i.e., $p_{i} = P (Z \geq z_{i})$ .
$tail [j] = Nag_TwoTailConfid$: The two tail (confidence interval) probability, i.e., $p_{i} = P (Z \leq |z_{i}|) - P (Z \leq - |z_{i}|)$ .
$tail [j] = Nag_TwoTailSignif$: The two tail (significance level) probability, i.e., $p_{i} = P (Z \geq |z_{i}|) + P (Z \leq - |z_{i}|)$ .

Constraint:

tail [j - 1] = Nag_LowerTail

Nag_UpperTail

Nag_TwoTailConfid

Nag_TwoTailSignif

, for

j = 1, 2, \dots, ltail

3: lp – IntegerInput

On entry: the length of the array p.

Constraint:

lp > 0

4: p[lp] – const doubleInput

On entry:

p_{i}

, the probabilities for the Normal distribution as defined by tail with

p_{i} = p [j]

j = (i - 1) mod lp

Constraint:

0.0 < p [j - 1] < 1.0

, for

j = 1, 2, \dots, lp

5: lxmu – IntegerInput

On entry: the length of the array xmu.

Constraint:

lxmu > 0

6: xmu[lxmu] – const doubleInput

On entry:

μ_{i}

, the means with

μ_{i} = xmu [j]

j = (i - 1) mod lxmu

7: lxstd – IntegerInput

On entry: the length of the array xstd.

Constraint:

lxstd > 0

8: xstd[lxstd] – const doubleInput

On entry:

σ_{i}

, the standard deviations with

σ_{i} = xstd [j]

j = (i - 1) mod lxstd

Constraint:

xstd [j - 1] > 0.0

, for

j = 1, 2, \dots, lxstd

9: x[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array x must be at least

\max (ltail, lxmu, lxstd, lp)

On exit:

x_{p_{i}}

, the deviates for the Normal distribution.

10: ivalid[ $\dim$ ] – IntegerOutput

Note: the dimension, dim, of the array ivalid must be at least

\max (ltail, lxmu, lxstd, lp)

On exit:

ivalid [i - 1]

indicates any errors with the input arguments, with

$ivalid [i - 1] = 0$

No error.

$ivalid [i - 1] = 1$

On entry,

invalid value supplied in tail when calculating

x_{p_{i}}

$ivalid [i - 1] = 2$

On entry,	$p_{i} \leq 0.0$ ,
or	$p_{i} \geq 1.0$ .

$ivalid [i - 1] = 3$

On entry,

σ_{i} \leq 0.0

11: fail – NagError *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, $array size = ⟨value⟩$ .
Constraint: $lp > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $ltail > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $lxmu > 0$ .
On entry, $array size = ⟨value⟩$ .
Constraint: $lxstd > 0$ .
NE_BAD_PARAM: On entry, argument $⟨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.

8 Parallelism and Performance

Not applicable.

9 Further Comments

None.

10 Example

This example reads vectors of values for

μ_{i}

σ_{i}

and

p_{i}

and prints the corresponding deviates.

NAG Library Function Documentnag_deviates_normal_vector (g01tac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG Library Function Document

nag_deviates_normal_vector (g01tac)