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_ssqmat_update (g02bt)

## Purpose

nag_correg_ssqmat_update (g02bt) updates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean, for a new observation. The data may be weighted.

## Syntax

[sw, xbar, c, ifail] = g02bt(wt, x, sw, xbar, c, 'mean', mean, 'm', m, 'incx', incx)
[sw, xbar, c, ifail] = nag_correg_ssqmat_update(wt, x, sw, xbar, c, 'mean', mean, 'm', m, 'incx', incx)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 23: incx now optional (default 1)
Mark 24: mean optional
.

## Description

nag_correg_ssqmat_update (g02bt) is an adaptation of West's WV2 algorithm; see West (1979). This function updates the weighted means of variables and weighted sums of squares and cross-products or weighted sums of squares and cross-products of deviations about the mean for observations on m$m$ variables Xj${X}_{j}$, for j = 1,2,,m$j=1,2,\dots ,m$. For the first i1$i-1$ observations let the mean of the j$j$th variable be xj(i1)${\stackrel{-}{x}}_{j}\left(i-1\right)$, the cross-product about the mean for the j$j$th and k$k$th variables be cjk(i1)${c}_{jk}\left(i-1\right)$ and the sum of weights be Wi1${W}_{i-1}$. These are updated by the i$i$th observation, xij${x}_{ij}$, for j = 1,2,,m$\mathit{j}=1,2,\dots ,m$, with weight wi${w}_{i}$ as follows:
 Wi = Wi − 1 + wi,  xj(i) = xj(i − 1) + (wi)/(Wi)(xj − xj(i − 1)),  j = 1,2, … ,m $Wi=Wi-1+wi, x-j(i)=x-j(i-1)+wiWi(xj-x-j(i-1)), j=1,2,…,m$
and
 cjk(i) = cjk(i − 1) + (wi)/(Wi)(xj − xj(i − 1))(xk − xk(i − 1))Wi − 1,   j = 1,2, … ,m;k = j,j + 1,2, … ,m. $cjk(i)=cjk(i- 1)+wiWi(xj-x-j(i- 1))(xk-x-k(i- 1))Wi- 1, j= 1,2,…,m;k=j,j+ 1,2,…,m.$
The algorithm is initialized by taking xj(1) = x1j${\stackrel{-}{x}}_{j}\left(1\right)={x}_{1j}$, the first observation and cij(1) = 0.0${c}_{ij}\left(1\right)=0.0$.
For the unweighted case wi = 1${w}_{i}=1$ and Wi = i${W}_{i}=i$ for all i$i$.

## 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:     wt – double scalar
The weight to use for the current observation, wi${w}_{i}$.
For unweighted means and cross-products set wt = 1.0${\mathbf{wt}}=1.0$. The use of a suitable negative value of wt, e.g., wi$-{w}_{i}$ will have the effect of deleting the observation.
2:     x(${\mathbf{m}}×{\mathbf{incx}}$) – double array
x((j1) × incx + 1)${\mathbf{x}}\left(\left(j-1\right)×{\mathbf{incx}}+1\right)$ must contain the value of the j$j$th variable for the current observation, j = 1,2,,m$j=1,2,\dots ,m$.
3:     sw – double scalar
The sum of weights for the previous observations, Wi1${W}_{i-1}$.
sw = 0.0${\mathbf{sw}}=0.0$
The update procedure is initialized.
sw + wt = 0.0${\mathbf{sw}}+{\mathbf{wt}}=0.0$
All elements of xbar and c are set to zero.
Constraint: sw0.0${\mathbf{sw}}\ge 0.0$ and sw + wt0.0${\mathbf{sw}}+{\mathbf{wt}}\ge 0.0$.
4:     xbar(m) – double array
m, the dimension of the array, must satisfy the constraint m1${\mathbf{m}}\ge 1$.
If sw = 0.0${\mathbf{sw}}=0.0$, xbar is initialized, otherwise xbar(j)${\mathbf{xbar}}\left(\mathit{j}\right)$ must contain the weighted mean of the j$\mathit{j}$th variable for the previous (i1)$\left(\mathit{i}-1\right)$ observations, xj(i1)${\stackrel{-}{x}}_{\mathit{j}}\left(\mathit{i}-1\right)$, for j = 1,2,,m$\mathit{j}=1,2,\dots ,m$.
5:     c((m × m + m) / 2$\left({\mathbf{m}}×{\mathbf{m}}+{\mathbf{m}}\right)/2$) – double array
If sw0.0${\mathbf{sw}}\ne 0.0$, c must contain the upper triangular part of the matrix of weighted sums of squares and cross-products or weighted sums of squares and cross-products of deviations about the mean. It is stored packed form by column, i.e., the cross-product between the j$j$th and k$k$th variable, kj$k\ge j$, is stored in c(k × (k1) / 2 + j)${\mathbf{c}}\left(k×\left(k-1\right)/2+j\right)$.

### Optional Input Parameters

1:     mean – string (length ≥ 1)
Indicates whether nag_correg_ssqmat_update (g02bt) is to calculate sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean.
mean = 'M'${\mathbf{mean}}=\text{'M'}$
The sums of squares and cross-products of deviations about the mean are calculated.
mean = 'Z'${\mathbf{mean}}=\text{'Z'}$
The sums of squares and cross-products are calculated.
Default: 'M'$\text{'M'}$
Constraint: mean = 'M'${\mathbf{mean}}=\text{'M'}$ or 'Z'$\text{'Z'}$.
2:     m – int64int32nag_int scalar
Default: The dimension of the array xbar.
m$m$, the number of variables.
Constraint: m1${\mathbf{m}}\ge 1$.
3:     incx – int64int32nag_int scalar
The increment of x. Two situations are common.
If incx = 1${\mathbf{incx}}=1$, the data values are to be found in consecutive locations in x, i.e., in a column.
If incx = ldx${\mathbf{incx}}=\mathit{ldx}$, for some positive integer ldx$\mathit{ldx}$, the data values are to be found as a row of an array with first dimension ldx$\mathit{ldx}$.
Default: 1$1$
Constraint: incx > 0${\mathbf{incx}}>0$.

None.

### Output Parameters

1:     sw – double scalar
Contains the updated sum of weights, Wi${W}_{i}$.
2:     xbar(m) – double array
xbar(j)${\mathbf{xbar}}\left(\mathit{j}\right)$ contains the weighted mean of the j$\mathit{j}$th variable, xj(i)${\stackrel{-}{x}}_{\mathit{j}}\left(\mathit{i}\right)$, for j = 1,2,,m$\mathit{j}=1,2,\dots ,m$.
3:     c((m × m + m) / 2$\left({\mathbf{m}}×{\mathbf{m}}+{\mathbf{m}}\right)/2$) – double array
The update sums of squares and cross-products stored as on input.
4:     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:
ifail = 1${\mathbf{ifail}}=1$
 On entry, m < 1${\mathbf{m}}<1$, or incx < 1${\mathbf{incx}}<1$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, sw < 0.0${\mathbf{sw}}<0.0$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, (sw + wt) < 0.0$\left({\mathbf{sw}}+{\mathbf{wt}}\right)<0.0$, the current weight causes the sum of weights to be less than 0.0$0.0$.
ifail = 4${\mathbf{ifail}}=4$
 On entry, mean ≠ 'M'${\mathbf{mean}}\ne \text{'M'}$ or 'Z'$\text{'Z'}$.

## Accuracy

For a detailed discussion of the accuracy of this method see Chan et al. (1982) and West (1979).

nag_correg_ssqmat_update (g02bt) may be used to update the results returned by nag_correg_ssqmat (g02bu).
nag_correg_ssqmat_to_corrmat (g02bw) may be used to calculate the correlation matrix from the matrix of sums of squares and cross-products of deviations about the mean and the matrix may be scaled using to produce a variance-covariance matrix.

## Example

```function nag_correg_ssqmat_update_example
wt = 0.13;
x = [9.1231;
3.7011;
4.523];
sw = 0;
xbar = zeros(3,1);
c = zeros(6,1);
[swOut, xbarOut, cOut, ifail] = nag_correg_ssqmat_update(wt, x, sw, xbar, c)
```
```

swOut =

0.1300

xbarOut =

9.1231
3.7011
4.5230

cOut =

0
0
0
0
0
0

ifail =

0

```
```function g02bt_example
wt = 0.13;
x = [9.1231;
3.7011;
4.523];
sw = 0;
xbar = zeros(3,1);
c = zeros(6,1);
[swOut, xbarOut, cOut, ifail] = g02bt(wt, x, sw, xbar, c)
```
```

swOut =

0.1300

xbarOut =

9.1231
3.7011
4.5230

cOut =

0
0
0
0
0
0

ifail =

0

```