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_correg_corrmat (g02bx)

## Purpose

nag_correg_corrmat (g02bx) calculates the sample means, the standard deviations, the variance-covariance matrix, and the matrix of Pearson product-moment correlation coefficients for a set of data. Weights may be used.

## Syntax

[xbar, std, v, r, ifail] = g02bx(x, 'nonzwt', nonzwt, 'n', n, 'm', m, 'wt', wt)
[xbar, std, v, r, ifail] = nag_correg_corrmat(x, 'nonzwt', nonzwt, 'n', n, 'm', m, 'wt', wt)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: n has been made optional
Mark 23: nonzwt added to interface, weight dropped from interface, wt now optional
.

## Description

nag_correg_corrmat (g02bx) uses a one-pass algorithm to compute the (optionally weighted) means and sums of squares and cross-products of deviations about the means. The algorithm uses a single pass updating algorithm as implemented by nag_correg_ssqmat (g02bu). The variance-covariance matrix, the standard deviations and the Pearson product-moment correlation matrix are then computed from these basic results, the latter by means of nag_correg_ssqmat_to_corrmat (g02bw).

## References

Chan T F, Golub G H and Leveque R J (1982) Updating Formulae and a Pairwise Algorithm for Computing Sample Variances Compstat, Physica-Verlag
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

## Parameters

### Compulsory Input Parameters

1:     x(ldx,m) – double array
ldx, the first dimension of the array, must satisfy the constraint ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
x(i,j)${\mathbf{x}}\left(\mathit{i},\mathit{j}\right)$ must contain the i$\mathit{i}$th observation for the j$\mathit{j}$th variable, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$ and j = 1,2,,m$\mathit{j}=1,2,\dots ,{\mathbf{m}}$.

### Optional Input Parameters

1:     nonzwt – string (length ≥ 1)
The variance calculation uses a divisor which is either the number of weights or the number of nonzero weights.
Default: 'W'$\text{'W'}$
Constraint: nonzwt = 'W'${\mathbf{nonzwt}}=\text{'W'}$ or 'V'$\text{'V'}$.
2:     n – int64int32nag_int scalar
Default: The first dimension of the array x.
The number of data observations in the sample.
Constraint: n > 1${\mathbf{n}}>1$.
3:     m – int64int32nag_int scalar
Default: The second dimension of the array x.
The number of variables.
Constraint: m1${\mathbf{m}}\ge 1$.
4:     wt(n${\mathbf{n}}$) – double array
Note: the dimension of the array wt must be at least n${\mathbf{n}}$ if weight = 'W'$\mathit{weight}=\text{'W'}$ or 'V'$\text{'V'}$, and at least 1$1$ otherwise.
The optional weights.
If provided, wt(i)${\mathbf{wt}}\left(i\right)$ must contain the weight for the i$i$th observation. When nonzwt = 'W'${\mathbf{nonzwt}}=\text{'W'}$ the effective number of observations is given by the sum of these weights as opposed to the number of nonzero weights when nonzwt = 'V'${\mathbf{nonzwt}}=\text{'V'}$.
Constraint: if weight = 'W'$\mathit{weight}=\text{'W'}$ or 'V'$\text{'V'}$, i = 1n wt(i) > 1.0$\sum _{\mathit{i}=1}^{{\mathbf{n}}}{\mathbf{wt}}\left(\mathit{i}\right)>1.0$, wt(i)0.0${\mathbf{wt}}\left(\mathit{i}\right)\ge 0.0$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,{\mathbf{n}}$.

weight ldx ldv

### Output Parameters

1:     xbar(m) – double array
The sample means. xbar(j)${\mathbf{xbar}}\left(j\right)$ contains the mean of the j$j$th variable.
2:     std(m) – double array
The standard deviations. std(j)${\mathbf{std}}\left(j\right)$ contains the standard deviation for the j$j$th variable.
3:     v(ldv,m) – double array
ldvm$\mathit{ldv}\ge {\mathbf{m}}$.
The variance-covariance matrix. v(j,k)${\mathbf{v}}\left(\mathit{j},\mathit{k}\right)$ contains the covariance between variables j$\mathit{j}$ and k$\mathit{k}$, for j = 1,2,,m$\mathit{j}=1,2,\dots ,{\mathbf{m}}$ and k = 1,2,,m$\mathit{k}=1,2,\dots ,{\mathbf{m}}$.
4:     r(ldv,m) – double array
ldvm$\mathit{ldv}\ge {\mathbf{m}}$.
The matrix of Pearson product-moment correlation coefficients. r(j,k)${\mathbf{r}}\left(j,k\right)$ contains the correlation coefficient between variables j$j$ and k$k$.
5:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Note: nag_correg_corrmat (g02bx) may return useful information for one or more of the following detected errors or 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.

ifail = 1${\mathbf{ifail}}=1$
 On entry, m < 1${\mathbf{m}}<1$, or n ≤ 1${\mathbf{n}}\le 1$, or ldx < n$\mathit{ldx}<{\mathbf{n}}$, or ldv < m$\mathit{ldv}<{\mathbf{m}}$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, weight ≠ 'U'$\mathit{weight}\ne \text{'U'}$, 'V'$\text{'V'}$ or 'W'$\text{'W'}$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, weight = 'W'$\mathit{weight}=\text{'W'}$ or 'V'$\text{'V'}$ and a value of wt < 0.0${\mathbf{wt}}<0.0$.
ifail = 4${\mathbf{ifail}}=4$
weight = 'W'$\mathit{weight}=\text{'W'}$ and the sum of weights is not greater than 1.0$1.0$, or weight = 'V'$\mathit{weight}=\text{'V'}$ and fewer than 2$2$ observations have nonzero weights.
W ifail = 5${\mathbf{ifail}}=5$
A variable has a zero variance. In this case v and std are returned as calculated but r will contain zero for any correlation involving a variable with zero variance.

## Accuracy

For a discussion of the accuracy of the one pass algorithm see Chan et al. (1982) and West (1979).

None.

## Example

```function nag_correg_corrmat_example
x = [11.25, 48.9, 7.43, 2.27, 15.48;
10.87, 47.7, 7.45, 1.971, 14.97;
11.18, 48.2, 7.44, 1.979, 14.2;
10.62, 49, 7.38, 2.026, 15.02;
11.02, 47.4, 7.43, 1.974, 12.92;
10.83, 48.3, 7.72, 2.124, 13.58;
11.18, 49.3, 7.05, 2.064, 14.12;
11.05, 48.2, 6.95, 2.001, 15.34;
11.15, 49.1, 7.12, 2.035, 14.52;
11.23, 48.6, 7.28, 1.97, 15.25;
10.94, 49.9, 7.45, 1.974, 15.34;
11.18, 49, 7.34, 1.942, 14.48;
11.02, 48.2, 7.29, 2.063, 12.92;
10.99, 47.8, 7.37, 1.973, 13.61;
11.03, 48.9, 7.45, 1.974, 14.2;
11.09, 48.8, 7.08, 2.039, 14.51;
11.46, 51.2, 6.75, 2.008, 16.07;
11.57, 49.8, 7, 1.944, 16.6;
11.07, 47.9, 7.04, 1.947, 13.41;
10.89, 49.6, 7.07, 1.798, 15.84];
[xbar, std, v, r, ifail] = nag_correg_corrmat(x)
```
```

xbar =

11.0810
48.7900
7.2545
2.0038
14.6190

std =

0.2132
0.9002
0.2349
0.0902
1.0249

v =

0.0455    0.0847   -0.0272    0.0013    0.0855
0.0847    0.8104   -0.1070   -0.0055    0.6511
-0.0272   -0.1070    0.0552    0.0059   -0.1048
0.0013   -0.0055    0.0059    0.0081   -0.0138
0.0855    0.6511   -0.1048   -0.0138    1.0504

r =

1.0000    0.4416   -0.5427    0.0696    0.3912
0.4416    1.0000   -0.5058   -0.0678    0.7057
-0.5427   -0.5058    1.0000    0.2768   -0.4352
0.0696   -0.0678    0.2768    1.0000   -0.1494
0.3912    0.7057   -0.4352   -0.1494    1.0000

ifail =

0

```
```function g02bx_example
x = [11.25, 48.9, 7.43, 2.27, 15.48;
10.87, 47.7, 7.45, 1.971, 14.97;
11.18, 48.2, 7.44, 1.979, 14.2;
10.62, 49, 7.38, 2.026, 15.02;
11.02, 47.4, 7.43, 1.974, 12.92;
10.83, 48.3, 7.72, 2.124, 13.58;
11.18, 49.3, 7.05, 2.064, 14.12;
11.05, 48.2, 6.95, 2.001, 15.34;
11.15, 49.1, 7.12, 2.035, 14.52;
11.23, 48.6, 7.28, 1.97, 15.25;
10.94, 49.9, 7.45, 1.974, 15.34;
11.18, 49, 7.34, 1.942, 14.48;
11.02, 48.2, 7.29, 2.063, 12.92;
10.99, 47.8, 7.37, 1.973, 13.61;
11.03, 48.9, 7.45, 1.974, 14.2;
11.09, 48.8, 7.08, 2.039, 14.51;
11.46, 51.2, 6.75, 2.008, 16.07;
11.57, 49.8, 7, 1.944, 16.6;
11.07, 47.9, 7.04, 1.947, 13.41;
10.89, 49.6, 7.07, 1.798, 15.84];
[xbar, std, v, r, ifail] = g02bx(x)
```
```

xbar =

11.0810
48.7900
7.2545
2.0038
14.6190

std =

0.2132
0.9002
0.2349
0.0902
1.0249

v =

0.0455    0.0847   -0.0272    0.0013    0.0855
0.0847    0.8104   -0.1070   -0.0055    0.6511
-0.0272   -0.1070    0.0552    0.0059   -0.1048
0.0013   -0.0055    0.0059    0.0081   -0.0138
0.0855    0.6511   -0.1048   -0.0138    1.0504

r =

1.0000    0.4416   -0.5427    0.0696    0.3912
0.4416    1.0000   -0.5058   -0.0678    0.7057
-0.5427   -0.5058    1.0000    0.2768   -0.4352
0.0696   -0.0678    0.2768    1.0000   -0.1494
0.3912    0.7057   -0.4352   -0.1494    1.0000

ifail =

0

```