NAG Library Routine Document

G02BXF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     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:     N – INTEGERInput

On entry: the number of data observations in the sample.

Constraint: $\mathbf{N}>1$.

3:     M – INTEGERInput

On entry: the number of variables.

Constraint: $\mathbf{M}\ge 1$.

4:     X(LDX,M) – REAL (KIND=nag_wp) arrayInput

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:     LDX – INTEGERInput

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:     WT($*$) – REAL (KIND=nag_wp) arrayInput

Note: the dimension of the array WT must be at least $\mathbf{N}$ if $\mathbf{WEIGHT}=\text{'W'}$ or $\text{'V'}$, and at least $1$ otherwise.

On entry: the optional weights.

If $\mathbf{WEIGHT}=\text{'W'}$ or $\text{'V'}$, $\mathbf{WT}\left(i\right)$ must contain the weight for the $i$th observation. When $\mathbf{WEIGHT}=\text{'W'}$ the effective number of observations is given by the sum of these weights as opposed to the number of nonzero weights when $\mathbf{WEIGHT}=\text{'V'}$.

If $\mathbf{WEIGHT}=\text{'U'}$, WT is not referenced.

Constraint: if $\mathbf{WEIGHT}=\text{'W'}$ or $\text{'V'}$, ${\displaystyle \sum _{\mathit{i}=1}^{\mathbf{N}}}\mathbf{WT}\left(\mathit{i}\right)>1.0$, $\mathbf{WT}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,\mathbf{N}$.

7:     XBAR(M) – REAL (KIND=nag_wp) arrayOutput

On exit: the sample means. $\mathbf{XBAR}\left(j\right)$ contains the mean of the $j$th variable.

8:     STD(M) – REAL (KIND=nag_wp) arrayOutput

On exit: the standard deviations. $\mathbf{STD}\left(j\right)$ contains the standard deviation for the $j$th variable.

9:     V(LDV,M) – REAL (KIND=nag_wp) arrayOutput

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:   LDV – INTEGERInput

On entry: the first dimension of the arrays R and V as declared in the (sub)program from which G02BXF is called.

Constraint: $\mathbf{LDV}\ge \mathbf{M}$.

11:   R(LDV,M) – REAL (KIND=nag_wp) arrayOutput

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:   IFAIL – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this routine the values of the output parameters may be useful even if $\mathbf{IFAIL}\ne \mathbf{0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{ or }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).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

On entry,	$\mathbf{M}<1$,
or	$\mathbf{N}\le 1$,
or	$\mathbf{LDX}<\mathbf{N}$,
or	$\mathbf{LDV}<\mathbf{M}$.

$\mathbf{IFAIL}=2$

On entry,

$\mathbf{WEIGHT}\ne \text{'U'}$, $\text{'V'}$ or $\text{'W'}$.

$\mathbf{IFAIL}=3$

On entry,

$\mathbf{WEIGHT}=\text{'W'}$ or $\text{'V'}$ and a value of $\mathbf{WT}<0.0$.

$\mathbf{IFAIL}=4$

$\mathbf{WEIGHT}=\text{'W'}$ and the sum of weights is not greater than $1.0$, or $\mathbf{WEIGHT}=\text{'V'}$ and fewer than $2$ observations have nonzero weights.

$\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.

7  Accuracy

8  Further Comments

9  Example

9.1  Program Text

Program Text (g02bxfe.f90)

9.2  Program Data

Program Data (g02bxfe.d)

9.3  Program Results

Program Results (g02bxfe.r)