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_prob_normal_vector (g01sa)

▸▿ 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_prob_normal_vector (g01sa) returns a number of one or two tail probabilities for the Normal distribution.

Syntax

[p, ivalid, ifail] = g01sa(tail, x, xmu, xstd, 'ltail', ltail, 'lx', lx, 'lxmu', lxmu, 'lxstd', lxstd)

[p, ivalid, ifail] = nag_stat_prob_normal_vector(tail, x, xmu, xstd, 'ltail', ltail, 'lx', lx, 'lxmu', lxmu, 'lxstd', lxstd)

Description

The lower tail probability for the Normal distribution,

P (X_{i} \leq x_{i})

is defined by:

P (X_{i} \leq x_{i}) = \int_{- \infty}^{x_{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 relationship

P (X_{i} \leq x_{i}) = \frac{1}{2} erfc (\frac{- (x_{i} - μ_{i})}{\sqrt{2} σ_{i}})

is used, where erfc is the complementary error function, and is computed using nag_specfun_erfc_real (s15ad).

When the two tail confidence probability is required the relationship

P (X_{i} \leq |x_{i}|) - P (X_{i} \leq - |x_{i}|) = \erf (\frac{|x_{i} - μ_{i}|}{\sqrt{2} σ_{i}}),

is used, where erf is the error function, and is computed using nag_specfun_erf_real (s15ae).

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

Parameters

Compulsory Input Parameters

1: $tail (ltail)$ – cell array of strings

Indicates which tail the returned probabilities should represent. Letting

Z

denote a variate from a standard Normal distribution, and

z_{i} = \frac{x_{i} - μ_{i}}{σ_{i}}

, then for

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

, for

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

$tail (j) ='L'$: The lower tail probability is returned, i.e., $p_{i} = P (Z \leq z_{i})$ .
$tail (j) ='U'$: The upper tail probability is returned, i.e., $p_{i} = P (Z \geq z_{i})$ .
$tail (j) ='C'$: The two tail (confidence interval) probability is returned, i.e., $p_{i} = P (Z \leq |z_{i}|) - P (Z \leq - |z_{i}|)$ .
$tail (j) ='S'$: The two tail (significance level) probability is returned, 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: $x (lx)$ – double array

x_{i}

, the Normal variate values with

x_{i} = x (j)

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

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: $lx$ – int64int32nag_int scalar: Default: the dimension of the array x.
The length of the array x.

Constraint: $lx > 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: $p (:)$ – double array

The dimension of the array p will be

\max (lx, ltail, lxmu, lxstd)

p_{i}

, the probabilities for the Normal distribution.

2: $ivalid (:)$ – int64int32nag_int array

The dimension of the array ivalid will be

\max (lx, ltail, lxmu, lxstd)

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

p_{i}

$ivalid (i) = 2$

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 or xstd was invalid.
Check ivalid for more information.

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

$ifail = 3$: Constraint: $lx > 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

Accuracy is limited by machine precision. For detailed error analysis see nag_specfun_erfc_real (s15ad) and nag_specfun_erf_real (s15ae).

Further Comments

None.

Example

Four values of tail, x, xmu and xstd are input and the probabilities calculated and printed.

Open in the MATLAB editor: g01sa_example

function g01sa_example


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

x    = [1.96; 1.96; 1.96; 1.96];
xmu  = [0; 0; 0; 0];
xstd = [1; 1; 1; 1];
tail = {'L'; 'U'; 'C'; 'S'};

% calculate probability
[prob, ivalid, ifail] = g01sa( ...
                               tail, x, xmu, xstd);

fprintf('tail    x       xmu      xstd    probability\n');
lx    = numel(x);
lxmu  = numel(xmu);
lxstd = numel(xstd);
ltail = numel(tail);
len   = max ([lx, lxmu, lxstd, ltail]);
for i=0:len-1
  fprintf(' %c %8.2f %8.2f %8.2f %8.3f\n', tail{mod(i,ltail)+1}, ...
          x(mod(i,lx)+1), xmu(mod(i,lxmu)+1), xstd(mod(i,lxstd)+1), prob(i+1));
end

g01sa example results

tail    x       xmu      xstd    probability
 L     1.96     0.00     1.00    0.975
 U     1.96     0.00     1.00    0.025
 C     1.96     0.00     1.00    0.950
 S     1.96     0.00     1.00    0.050

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

Chapter Contents

Chapter Introduction

NAG Toolbox