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)

C Header Interface

#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.

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)If $| 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)If $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)If $| 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 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.

4 References

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

5 Arguments

1: $ltail$ – Integer Input

On entry: the length of the array tail.

Constraint:

ltail > 0

2: $tail (ltail)$ – 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}} - μ_{i}}{σ_{i}}

, then for

j = ((i - 1) mod ltail) + 1

, for

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

$tail (j) ='L'$: The lower tail probability, i.e., $p_{i} = P (Z \leq z_{i})$ .
$tail (j) ='U'$: The upper tail probability, i.e., $p_{i} = P (Z \geq z_{i})$ .
$tail (j) ='C'$: The two tail (confidence interval) probability, i.e., $p_{i} = P (Z \leq | z_{i} |) - P (Z \leq - | z_{i} |)$ .
$tail (j) ='S'$: The two tail (significance level) probability, i.e., $p_{i} = P (Z \geq | z_{i} |) + P (Z \leq - | z_{i} |)$ .

Constraint:

tail (j) ='L'

'U'

'C'

'S'

, for

j = 1, 2, \dots, ltail

3: $lp$ – Integer Input

On entry: the length of the array p.

Constraint:

lp > 0

4: $p (lp)$ – Real (Kind=nag_wp) array Input

On entry:

p_{i}

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

p_{i} = p (j)

j = (i - 1) mod lp + 1

Constraint:

0.0 < p (j) < 1.0

, for

j = 1, 2, \dots, lp

5: $lxmu$ – Integer Input

On entry: the length of the array xmu.

Constraint:

lxmu > 0

6: $xmu (lxmu)$ – Real (Kind=nag_wp) array Input

On entry:

μ_{i}

, the means with

μ_{i} = xmu (j)

j = ((i - 1) mod lxmu) + 1

7: $lxstd$ – Integer Input

On entry: the length of the array xstd.

Constraint:

lxstd > 0

8: $xstd (lxstd)$ – Real (Kind=nag_wp) array Input

On entry:

σ_{i}

, the standard deviations with

σ_{i} = xstd (j)

j = ((i - 1) mod lxstd) + 1

Constraint:

xstd (j) > 0.0

, for

j = 1, 2, \dots, lxstd

9: $x (*)$ – Real (Kind=nag_wp) array Output

Note: the dimension 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 (*)$ – Integer array Output

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

\max (ltail, lxmu, lxstd, lp)

On exit:

ivalid (i)

indicates any errors with the input arguments, with

$ivalid (i) = 0$: No error.
$ivalid (i) = 1$: On entry, invalid value supplied in tail when calculating $x_{p_{i}}$ .
$ivalid (i) = 2$: On entry, $p_{i} \leq 0.0$ , or, $p_{i} \geq 1.0$ .
$ivalid (i) = 3$: On entry, $σ_{i} \leq 0.0$ .

11: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

- 1

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

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, at least one value of tail, xstd or p was invalid.
Check ivalid for more information.

$ifail = 2$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $ltail > 0$ .

$ifail = 3$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $lp > 0$ .

$ifail = 4$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $lxmu > 0$ .

$ifail = 5$: On entry, $array size = ⟨ value ⟩$ .
Constraint: $lxstd > 0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$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.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The accuracy is mainly limited by the machine precision.

8 Parallelism and Performance

g01taf is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads vectors of values for

μ_{i}

σ_{i}

and

p_{i}

and prints the corresponding deviates.

g01ta: FL CL CPP AD

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

▸▿ 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 FL Interface
g01taf (inv_cdf_normal_vector)