Integer type: int32 int64 nag_int show int32 show int32 show int64 show int64 show nag_int show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox

NAG Toolbox: nag_stat_inv_cdf_normal_vector (g01ta)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

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,

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 Vectorized Routines 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

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

2: $p (lp)$ – double array

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

3: $xmu (lxmu)$ – double array

μ_{i}

, the means with

μ_{i} = xmu (j)

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

4: $xstd (lxstd)$ – double array

σ_{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

Optional Input Parameters

1: $ltail$ – int64int32nag_int scalar: Default: the dimension of the array tail.
The length of the array tail.

Constraint: $ltail > 0$ .
2: $lp$ – int64int32nag_int scalar: Default: the dimension of the array p.
The length of the array p.

Constraint: $lp > 0$ .
3: $lxmu$ – int64int32nag_int scalar: Default: the dimension of the array xmu.
The length of the array xmu.

Constraint: $lxmu > 0$ .
4: $lxstd$ – int64int32nag_int scalar: Default: the dimension of the array xstd.
The length of the array xstd.

Constraint: $lxstd > 0$ .

Output Parameters

1: $x (:)$ – double array

The dimension of the array x will be

\max (ltail, lxmu, lxstd, lp)

x_{p_{i}}

, the deviates for the Normal distribution.

2: $ivalid (:)$ – int64int32nag_int array

The dimension of the array ivalid will be

\max (ltail, lxmu, lxstd, lp)

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

3: $ifail$ – int64int32nag_int scalar

ifail = 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$: On entry, at least one value of tail, xstd or p was invalid.
Check ivalid for more information.

$ifail = 2$: Constraint: $ltail > 0$ .

$ifail = 3$: Constraint: $lp > 0$ .

$ifail = 4$: Constraint: $lxmu > 0$ .

$ifail = 5$: Constraint: $lxstd > 0$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

The accuracy is mainly limited by the machine precision.

Further Comments

None.

Example

This example reads vectors of values for

μ_{i}

σ_{i}

and

p_{i}

and prints the corresponding deviates.

Open in the MATLAB editor: g01ta_example

function g01ta_example


fprintf('g01ta example results\n\n');

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

g01ta example results

tail    p              xmu      xstd      deviate
 L      0.975          0.0000   1.000     1.959964
 U      0.025          0.0000   1.000     1.959964
 C      0.950          0.0000   1.000     1.959964
 S      0.050          0.0000   1.000     1.959964

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox