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

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\left({X}_{i}\le {x}_{i}\right)$ is defined by:
 xi P(Xi ≤ xi) = ∫ Zi(Xi)dXi, − ∞
$P(Xi≤xi) = ∫ -∞ 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 (Xi ≤ xi) = (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 > 0${\mathbf{ltail}}>0$.
Indicates which tail the returned probabilities should represent. Letting Z$Z$ denote a variate from a standard Normal distribution, and zi = ( xi μi )/(σi)${z}_{i}=\frac{{x}_{i}-{\mu }_{i}}{{\sigma }_{i}}$, then for j = ((i1)  mod  ltail) + 1 , for i = 1,2,,max (lx,ltail,lxmu,lxstd)$\mathit{i}=1,2,\dots ,\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{lx}},{\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}}\right)$:
tail(j) = 'L'${\mathbf{tail}}\left(j\right)=\text{'L'}$
The lower tail probability is returned, i.e., pi = P(Zzi)${p}_{i}=P\left(Z\le {z}_{i}\right)$.
tail(j) = 'U'${\mathbf{tail}}\left(j\right)=\text{'U'}$
The upper tail probability is returned, i.e., pi = P(Zzi)${p}_{i}=P\left(Z\ge {z}_{i}\right)$.
tail(j) = 'C'${\mathbf{tail}}\left(j\right)=\text{'C'}$
The two tail (confidence interval) probability is returned, i.e., pi = P(Z|zi|)P(Z|zi|)${p}_{i}=P\left(Z\le |{z}_{i}|\right)-P\left(Z\le -|{z}_{i}|\right)$.
tail(j) = 'S'${\mathbf{tail}}\left(j\right)=\text{'S'}$
The two tail (significance level) probability is returned, i.e., pi = P(Z|zi|) + P(Z|zi|)${p}_{i}=P\left(Z\ge |{z}_{i}|\right)+P\left(Z\le -|{z}_{i}|\right)$.
Constraint: tail(j) = 'L'${\mathbf{tail}}\left(\mathit{j}\right)=\text{'L'}$, 'U'$\text{'U'}$, 'C'$\text{'C'}$ or 'S'$\text{'S'}$, for j = 1,2,,ltail$\mathit{j}=1,2,\dots ,{\mathbf{ltail}}$.
2:     x(lx) – double array
lx, the dimension of the array, must satisfy the constraint lx > 0${\mathbf{lx}}>0$.
xi${x}_{i}$, the Normal variate values with xi = x(j)${x}_{i}={\mathbf{x}}\left(j\right)$, j = ((i1)  mod  lx) + 1.
3:     xmu(lxmu) – double array
lxmu, the dimension of the array, must satisfy the constraint lxmu > 0${\mathbf{lxmu}}>0$.
μi${\mu }_{i}$, the means with μi = xmu(j)${\mu }_{i}={\mathbf{xmu}}\left(j\right)$, j = ((i1)  mod  lxmu) + 1.
4:     xstd(lxstd) – double array
lxstd, the dimension of the array, must satisfy the constraint lxstd > 0${\mathbf{lxstd}}>0$.
σi${\sigma }_{i}$, the standard deviations with σi = xstd(j)${\sigma }_{i}={\mathbf{xstd}}\left(j\right)$, j = ((i1)  mod  lxstd) + 1.
Constraint: xstd(j) > 0.0${\mathbf{xstd}}\left(\mathit{j}\right)>0.0$, for j = 1,2,,lxstd$\mathit{j}=1,2,\dots ,{\mathbf{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${\mathbf{ltail}}>0$.
2:     lx – int64int32nag_int scalar
Default: The dimension of the array x.
The length of the array x.
Constraint: lx > 0${\mathbf{lx}}>0$.
3:     lxmu – int64int32nag_int scalar
Default: The dimension of the array xmu.
The length of the array xmu.
Constraint: lxmu > 0${\mathbf{lxmu}}>0$.
4:     lxstd – int64int32nag_int scalar
Default: The dimension of the array xstd.
The length of the array xstd.
Constraint: lxstd > 0${\mathbf{lxstd}}>0$.

None.

### Output Parameters

1:     p( : $:$) – double array
Note: the dimension of the array p must be at least max (lx,ltail,lxmu,lxstd)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{lx}},{\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}}\right)$.
pi${p}_{i}$, 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)$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{lx}},{\mathbf{ltail}},{\mathbf{lxmu}},{\mathbf{lxstd}}\right)$.
ivalid(i)${\mathbf{ivalid}}\left(i\right)$ indicates any errors with the input arguments, with
ivalid(i) = 0${\mathbf{ivalid}}\left(i\right)=0$
No error.
ivalid(i) = 1${\mathbf{ivalid}}\left(i\right)=1$
 On entry, invalid value supplied in tail when calculating pi${p}_{i}$.
ivalid(i) = 2${\mathbf{ivalid}}\left(i\right)=2$
 On entry, σi ≤ 0.0${\sigma }_{i}\le 0.0$.
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{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${\mathbf{ifail}}=1$
On entry, at least one value of tail or xstd was invalid.
ifail = 2${\mathbf{ifail}}=2$
Constraint: ltail > 0${\mathbf{ltail}}>0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: lx > 0${\mathbf{lx}}>0$.
ifail = 4${\mathbf{ifail}}=4$
Constraint: lxmu > 0${\mathbf{lxmu}}>0$.
ifail = 5${\mathbf{ifail}}=5$
Constraint: lxstd > 0${\mathbf{lxstd}}>0$.
ifail = 999${\mathbf{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).

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

```