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)

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(Xixi)P(Xixi) is defined by:
xi
P(Xixi) = Zi(Xi)dXi,
P(Xixi) = - xi Zi(Xi)dXi ,
where
Zi(Xi) = 1/(sqrt(2πσi2)) e(Xiμi)2 / (2σi2) , < Xi < .
Zi(Xi) = 1 2πσi2 e -(Xi-μi)2/(2σi2) , - < Xi < .
The relationship
P (Xixi) = (1/2) erfc(( (xiμi) )/( sqrt(2) σi ))
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 (Xi|xi|) P (Xi|xi|) = erf(( |xiμi| )/( sqrt(2) σi )) ,
P (Xi|xi|) - 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 parameters by re-using elements of any arrays that are shorter than the total number of evaluations required. See Section [Vectorized s] 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
ltail, the dimension of the array, must satisfy the constraint ltail > 0ltail>0.
Indicates which tail the returned probabilities should represent. Letting ZZ denote a variate from a standard Normal distribution, and zi = ( xi μi )/(σi) zi = xi - μi σi , then for j = ((i1)  mod  ltail) + 1 j= ( (i-1) mod ltail ) +1 , for i = 1,2,,max (lx,ltail,lxmu,lxstd)i=1,2,,max(lx,ltail,lxmu,lxstd):
tail(j) = 'L'tailj='L'
The lower tail probability is returned, i.e., pi = P(Zzi)pi=P(Zzi).
tail(j) = 'U'tailj='U'
The upper tail probability is returned, i.e., pi = P(Zzi)pi=P(Zzi).
tail(j) = 'C'tailj='C'
The two tail (confidence interval) probability is returned, i.e., pi = P(Z|zi|)P(Z|zi|)pi=P(Z|zi|)-P(Z-|zi|).
tail(j) = 'S'tailj='S'
The two tail (significance level) probability is returned, i.e., pi = P(Z|zi|) + P(Z|zi|)pi=P(Z|zi|)+P(Z-|zi|).
Constraint: tail(j) = 'L'tailj='L', 'U''U', 'C''C' or 'S''S', for j = 1,2,,ltailj=1,2,,ltail.
2:     x(lx) – double array
lx, the dimension of the array, must satisfy the constraint lx > 0lx>0.
xixi, the Normal variate values with xi = x(j)xi=xj, j = ((i1)  mod  lx) + 1j=((i-1) mod lx)+1.
3:     xmu(lxmu) – double array
lxmu, the dimension of the array, must satisfy the constraint lxmu > 0lxmu>0.
μiμi, the means with μi = xmu(j)μi=xmuj, j = ((i1)  mod  lxmu) + 1j=((i-1) mod lxmu)+1.
4:     xstd(lxstd) – double array
lxstd, the dimension of the array, must satisfy the constraint lxstd > 0lxstd>0.
σiσi, the standard deviations with σi = xstd(j)σi=xstdj, j = ((i1)  mod  lxstd) + 1j=((i-1) mod lxstd)+1.
Constraint: xstd(j) > 0.0xstdj>0.0, for j = 1,2,,lxstdj=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 > 0ltail>0.
2:     lx – int64int32nag_int scalar
Default: The dimension of the array x.
The length of the array x.
Constraint: lx > 0lx>0.
3:     lxmu – int64int32nag_int scalar
Default: The dimension of the array xmu.
The length of the array xmu.
Constraint: lxmu > 0lxmu>0.
4:     lxstd – int64int32nag_int scalar
Default: The dimension of the array xstd.
The length of the array xstd.
Constraint: lxstd > 0lxstd>0.

Input Parameters Omitted from the MATLAB Interface

None.

Output Parameters

1:     p( : :) – double array
Note: the dimension of the array p must be at least max (lx,ltail,lxmu,lxstd)max(lx,ltail,lxmu,lxstd).
pipi, the probabilities for the Normal distribution.
2:     ivalid( : :) – int64int32nag_int array
Note: the dimension of the array ivalid must be at least max (lx,ltail,lxmu,lxstd)max(lx,ltail,lxmu,lxstd).
ivalid(i)ivalidi indicates any errors with the input arguments, with
ivalid(i) = 0ivalidi=0
No error.
ivalid(i) = 1ivalidi=1
On entry,invalid value supplied in tail when calculating pipi.
ivalid(i) = 2ivalidi=2
On entry,σi0.0σi0.0.
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=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 = 1ifail=1
On entry, at least one value of tail or xstd was invalid.
Check ivalid for more information.
  ifail = 2ifail=2
Constraint: ltail > 0ltail>0.
  ifail = 3ifail=3
Constraint: lx > 0lx>0.
  ifail = 4ifail=4
Constraint: lxmu > 0lxmu>0.
  ifail = 5ifail=5
Constraint: lxstd > 0lxstd>0.
  ifail = 999ifail=-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

function nag_stat_prob_normal_vector_example
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] = nag_stat_prob_normal_vector(tail, x, xmu, xstd);

fprintf('\nTail    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 %7d\n', tail{mod(i,ltail)+1}, x(mod(i,lx)+1), ...
         xmu(mod(i,lxmu)+1), xstd(mod(i,lxstd)+1), prob(i+1),  ivalid(i+1));
end
 

Tail    X       XMU      XSTD    Probability
 L     1.96     0.00     1.00    0.975       0
 U     1.96     0.00     1.00    0.025       0
 C     1.96     0.00     1.00    0.950       0
 S     1.96     0.00     1.00    0.050       0

function g01sa_example
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('\nTail    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 %7d\n', tail{mod(i,ltail)+1}, x(mod(i,lx)+1), ...
         xmu(mod(i,lxmu)+1), xstd(mod(i,lxstd)+1), prob(i+1),  ivalid(i+1));
end
 

Tail    X       XMU      XSTD    Probability
 L     1.96     0.00     1.00    0.975       0
 U     1.96     0.00     1.00    0.025       0
 C     1.96     0.00     1.00    0.950       0
 S     1.96     0.00     1.00    0.050       0


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–2013