hide long namesshow long names
hide short namesshow short names
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
    7  Accuracy
    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, PXixi is defined by:
PXixi = - xi ZiXidXi ,  
where
ZiXi = 1 2πσi2 e -Xi-μi2/2σi2 , - < Xi < .  
The relationship
P Xi xi = 12 erfc - xi - μi 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 Xixi - P Xi - xi = erf xi - μi 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:     tailltail – cell array of strings
Indicates which tail the returned probabilities should represent. Letting Z denote a variate from a standard Normal distribution, and zi = xi - μi σi , then for j= i-1 mod ltail +1 , for i=1,2,,maxlx,ltail,lxmu,lxstd:
tailj='L'
The lower tail probability is returned, i.e., pi=PZzi.
tailj='U'
The upper tail probability is returned, i.e., pi=PZzi.
tailj='C'
The two tail (confidence interval) probability is returned, i.e., pi=PZzi-PZ-zi.
tailj='S'
The two tail (significance level) probability is returned, i.e., pi=PZzi+PZ-zi.
Constraint: tailj='L', 'U', 'C' or 'S', for j=1,2,,ltail.
2:     xlx – double array
xi, the Normal variate values with xi=xj, j=i-1 mod lx+1.
3:     xmulxmu – double array
μi, the means with μi=xmuj, j=i-1 mod lxmu+1.
4:     xstdlxstd – double array
σi, the standard deviations with σi=xstdj, j=i-1 mod lxstd+1.
Constraint: xstdj>0.0, for j=1,2,,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 maxlx,ltail,lxmu,lxstd
pi, the probabilities for the Normal distribution.
2:     ivalid: int64int32nag_int array
The dimension of the array ivalid will be maxlx,ltail,lxmu,lxstd
ivalidi indicates any errors with the input arguments, with
ivalidi=0
No error.
ivalidi=1
On entry,invalid value supplied in tail when calculating pi.
ivalidi=2
On entry,σi0.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.
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

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015