# NAG FL Interfaceg02bxf (corrmat)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

g02bxf 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.

## 2Specification

Fortran Interface
 Subroutine g02bxf ( n, m, x, ldx, wt, xbar, std, v, ldv, r,
 Integer, Intent (In) :: n, m, ldx, ldv Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: x(ldx,m), wt(*) Real (Kind=nag_wp), Intent (Inout) :: v(ldv,m), r(ldv,m) Real (Kind=nag_wp), Intent (Out) :: xbar(m), std(m) Character (1), Intent (In) :: weight
#include <nag.h>
 void g02bxf_ (const char *weight, const Integer *n, const Integer *m, const double x[], const Integer *ldx, const double wt[], double xbar[], double std[], double v[], const Integer *ldv, double r[], Integer *ifail, const Charlen length_weight)
The routine may be called by the names g02bxf or nagf_correg_corrmat.

## 3Description

For $n$ observations on $m$ variables the one-pass algorithm of West (1979) as implemented in g02buf is used to compute the means, the standard deviations, the variance-covariance matrix, and the Pearson product-moment correlation matrix for $p$ selected variables. Suitables weights may be used to indicate multiple observations and to remove missing values. The quantities are defined by:
(a) The means
 $x ¯ j = ∑ i=1 n w i x ij ∑ i=1 n w i j = 1 , … , p$
(b) The variance-covariance matrix
 $C jk = ∑ i=1 n w i ( x ij - x ¯ j ) ( x ik - x ¯ k ) ∑ i=1 n w i - 1 j , k = 1 , … , p$
(c) The standard deviations
 $s j = C jj j = 1 , … , p$
(d) The Pearson product-moment correlation coefficients
 $R jk = C jk C jj C kk j , k = 1 , … , p$
where ${x}_{ij}$ is the value of the $i$th observation on the $j$th variable and ${w}_{i}$ is the weight for the $i$th observation which will be $1$ in the unweighted case.
Note that the denominator for the variance-covariance is ${\sum }_{i=1}^{n}{w}_{i}-1$, so the weights should be scaled so that the sum of weights reflects the true sample size.

## 4References

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

## 5Arguments

1: $\mathbf{weight}$Character(1) Input
On entry: indicates whether weights are to be used.
${\mathbf{weight}}=\text{'U'}$
Weights are not used and unit weights are assumed.
${\mathbf{weight}}=\text{'W'}$ or $\text{'V'}$
Weights are used and must be supplied in wt. The only difference between ${\mathbf{weight}}=\text{'W'}$ or ${\mathbf{weight}}=\text{'V'}$ is in computing the variance. If ${\mathbf{weight}}=\text{'W'}$ the divisor for the variance is the sum of the weights minus one and if ${\mathbf{weight}}=\text{'V'}$ the divisor is the number of observations with nonzero weights minus one. The former is useful if the weights represent the frequency of the observed values.
Constraint: ${\mathbf{weight}}=\text{'U'}$, $\text{'V'}$ or $\text{'W'}$.
2: $\mathbf{n}$Integer Input
On entry: the number of data observations in the sample.
Constraint: ${\mathbf{n}}>1$.
3: $\mathbf{m}$Integer Input
On entry: the number of variables.
Constraint: ${\mathbf{m}}\ge 1$.
4: $\mathbf{x}\left({\mathbf{ldx}},{\mathbf{m}}\right)$Real (Kind=nag_wp) array Input
On entry: ${\mathbf{x}}\left(\mathit{i},\mathit{j}\right)$ must contain the $\mathit{i}$th observation for the $\mathit{j}$th variable, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$ and $\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
5: $\mathbf{ldx}$Integer Input
On entry: the first dimension of the array x as declared in the (sub)program from which g02bxf is called.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
6: $\mathbf{wt}\left(*\right)$Real (Kind=nag_wp) array Input
Note: the dimension of the array wt must be at least ${\mathbf{n}}$ if ${\mathbf{weight}}=\text{'W'}$ or $\text{'V'}$.
On entry: $w$, the optional frequency weighting for each observation, with ${\mathbf{wt}}\left(i\right)={w}_{i}$. Usually ${w}_{i}$ will be an integral value corresponding to the number of observations associated with the $i$th data value, or zero if the $i$th data value is to be ignored. If ${\mathbf{weight}}=\text{'U'}$, ${w}_{i}$ is set to $1$ for all $i$ and wt is not referenced.
Constraints:
if ${\mathbf{weight}}=\text{'W'}$ or $\text{'V'}$,
• ${\mathbf{wt}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$;
• $\sum _{\mathit{i}=1}^{{\mathbf{n}}}{\mathbf{wt}}\left(\mathit{i}\right)>1.0$.
7: $\mathbf{xbar}\left({\mathbf{m}}\right)$Real (Kind=nag_wp) array Output
On exit: the sample means. ${\mathbf{xbar}}\left(j\right)$ contains the mean of the $j$th variable.
8: $\mathbf{std}\left({\mathbf{m}}\right)$Real (Kind=nag_wp) array Output
On exit: the standard deviations. ${\mathbf{std}}\left(j\right)$ contains the standard deviation for the $j$th variable.
9: $\mathbf{v}\left({\mathbf{ldv}},{\mathbf{m}}\right)$Real (Kind=nag_wp) array Output
On exit: the variance-covariance matrix. ${\mathbf{v}}\left(\mathit{j},\mathit{k}\right)$ contains the covariance between variables $\mathit{j}$ and $\mathit{k}$, for $\mathit{j}=1,2,\dots ,{\mathbf{m}}$ and $\mathit{k}=1,2,\dots ,{\mathbf{m}}$.
10: $\mathbf{ldv}$Integer Input
On entry: the first dimension of the array v and the first dimension of the array r as declared in the (sub)program from which g02bxf is called.
Constraint: ${\mathbf{ldv}}\ge {\mathbf{m}}$.
11: $\mathbf{r}\left({\mathbf{ldv}},{\mathbf{m}}\right)$Real (Kind=nag_wp) array Output
On exit: the matrix of Pearson product-moment correlation coefficients. ${\mathbf{r}}\left(j,k\right)$ contains the correlation coefficient between variables $j$ and $k$.
12: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended since useful values can be provided in some output arguments even when ${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
Note: in some cases g02bxf may return useful information.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{ldv}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldv}}\ge {\mathbf{m}}$.
On entry, ${\mathbf{ldx}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ldx}}\ge {\mathbf{n}}$.
On entry, ${\mathbf{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\ge 1$.
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}>1$.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{weight}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{weight}}=\text{'U'}$, $\text{'V'}$ or $\text{'W'}$
${\mathbf{ifail}}=3$
On entry, at least one value of wt is negative.
Constraint: ${\mathbf{wt}}\left(i\right)\ge 0$, for $i=1,2,\dots ,{\mathbf{n}}$.
${\mathbf{ifail}}=4$
On entry, $⟨\mathit{\text{value}}⟩$ observations have nonzero weight.
Constraint: at least two observations must have a nonzero weight.
On entry, Sum of the weights is $⟨\mathit{\text{value}}⟩$.
Constraint: Sum of the weights must be greater than $1$.
${\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.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

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

## 8Parallelism and Performance

g02bxf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

None.

## 10Example

The data are some of the results from 1988 Olympic Decathlon. They are the times (in seconds) for the 100m and 400m races and the distances (in metres) for the long jump, high jump and shot. Twenty observations are input and the correlation matrix is computed and printed.

### 10.1Program Text

Program Text (g02bxfe.f90)

### 10.2Program Data

Program Data (g02bxfe.d)

### 10.3Program Results

Program Results (g02bxfe.r)