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_summary_2var (g01ab)

## Purpose

nag_stat_summary_2var (g01ab) computes the means, standard deviations, corrected sums of squares and products, maximum and minimum values, and the product-moment correlation coefficient for two variables. Unequal weighting may be given.

## Syntax

[res, ifail] = g01ab(x1, x2, 'n', n, 'wt', wt)
[res, ifail] = nag_stat_summary_2var(x1, x2, 'n', n, 'wt', wt)
Note: the interface to this routine has changed since earlier releases of the toolbox:
 At Mark 23: wt is no longer an output parameter

## Description

The data consist of two samples of $n$ observations, denoted by ${x}_{i}$, and ${y}_{i}$, for $i=1,2,\dots ,n$, with corresponding weights ${w}_{i}$, for $\mathit{i}=1,2,\dots ,n$.
If no specific weighting is given, then each ${w}_{i}$ is set to $1.0$ in nag_stat_summary_2var (g01ab).
The quantities calculated are:
(a) The sum of weights,
 $W=∑i=1nwi.$
(b) The means,
 $x-=∑i= 1nwixiW, y-=∑i= 1nwiyiW.$
(c) The corrected sums of squares and products
 $c11=∑i=1n wi xi-x- 2 c21=c12=∑i=1n wi xi-x- yi-y- c22=∑i=1n wi yi-y- 2 .$
(d) The standard deviations
 $sj= cjj d , where j= 1,2 and d=W- ∑ i= 1 n wi2 W .$
(e) The product-moment correlation coefficient
 $R= c12 c11 c22 .$
(f) The minimum and maximum elements in each of the two samples.
(g) The number of pairs of observations, $m$, for which ${w}_{i}>0$, i.e., the number of valid observations. The quantities in (d) and (e) above will only be computed if $m\ge 2$. All other items are computed if $m\ge 1$.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x1}\left({\mathbf{n}}\right)$ – double array
The observations from the first sample, ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
2:     $\mathrm{x2}\left({\mathbf{n}}\right)$ – double array
The observations from the second sample, ${y}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the arrays x1, x2, wt. (An error is raised if these dimensions are not equal.)
$n$, the number of pairs of observations.
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathrm{wt}\left({\mathbf{n}}\right)$ – double array
If weights are being supplied then the elements of wt must contain the weights associated with the observations, ${w}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
Constraint: if $\mathbf{iwt}=1$, ${\mathbf{wt}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,{\mathbf{n}}$.

### Output Parameters

1:     $\mathrm{res}\left(13\right)$ – double array
The elements of res contain the following results:
 ${\mathbf{res}}\left(1\right)$ mean of the first sample, $\stackrel{-}{x}$; ${\mathbf{res}}\left(2\right)$ mean of the second sample, $\stackrel{-}{y}$; ${\mathbf{res}}\left(3\right)$ standard deviation of the first sample, ${s}_{1}$; ${\mathbf{res}}\left(4\right)$ standard deviation of the second sample, ${s}_{2}$; ${\mathbf{res}}\left(5\right)$ corrected sum of squares of the first sample, ${c}_{11}$; ${\mathbf{res}}\left(6\right)$ corrected sum of products of the two samples, ${c}_{12}$; ${\mathbf{res}}\left(7\right)$ corrected sum of squares of the second sample, ${c}_{22}$; ${\mathbf{res}}\left(8\right)$ product-moment correlation coefficient, $R$; ${\mathbf{res}}\left(9\right)$ minimum of the first sample; ${\mathbf{res}}\left(10\right)$ maximum of the first sample; ${\mathbf{res}}\left(11\right)$ minimum of the second sample; ${\mathbf{res}}\left(12\right)$ maximum of the second sample; ${\mathbf{res}}\left(13\right)$ sum of weights, $\sum _{i=1}^{n}{w}_{i}$ ($={\mathbf{n}}$, if wt is null on entry).
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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.

${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$.
W  ${\mathbf{ifail}}=2$
The number of valid cases, $m$, is $1$, hence the standard deviation, 3(d), and the product-moment correlation coefficient, 3(e), cannot be calculated.
${\mathbf{ifail}}=3$
The number of valid cases, $m$, is $0$, or at least one of the weights is negative.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The method used is believed to be stable.

The time taken by nag_stat_summary_2var (g01ab) increases linearly with $n$.

## Example

In the program below, NPROB determines the number of datasets to be analysed. For each analysis, a set of observations and, optionally, weights, is read and printed. After calling nag_stat_summary_2var (g01ab), all the calculated quantities are printed. In the example, there is one set of data, with $29$ (unweighted) pairs of observations.
```function g01ab_example

fprintf('g01ab example results\n\n');

x1 = [350     550     380     510    1270     300    2630     810 ...
140     450    2280     250     540     720      90     480 ...
180    3160     220     860     300    1460     400     620 ...
120     780     230    1070     160];
x2 = [ 47      95     211     122     530      38     278     309 ...
75      43     407     142      89     159      35     103 ...
78     969     120     333      73     147      30     100 ...
55     145     101     468      86];
n = size(x1,2);

[res, ifail] = g01ab(x1, x2);

fprintf('Number of cases    %7d\n',n);
fprintf('Data as input -\n');
v1 = 'Var  1';
v2 = 'Var  2';
fprintf('%12s%12s%12s%12s%12s%12s\n', v1, v2, v1, v2, v1, v2);
fprintf('%12.1f%12.1f%12.1f%12.1f%12.1f%12.1f\n',[x1; x2])
fprintf('\n\n');
fprintf('No. of valid cases %7d\n\n',n);
fprintf('%30s%30s\n', 'Variable 1', 'Variable 2');
fprintf('Mean               %11.1f%30.1f\n',res(1:2));
fprintf('Minimum            %11.1f%30.1f\n',res(9:2:11));
fprintf('Maximum            %11.1f%30.1f\n',res(10:2:12));
fprintf('Standard deviation %11.1f%30.1f\n',res(3:4));
fprintf('Sum of squares     %11.1f%30.1f\n',res(5:2:7));
fprintf('Sum of weights     %26.4f\n',res(13));
fprintf('Sum of products    %26.4f\n',res(6));
fprintf('Correlation        %26.4f\n',res(8));

```
```g01ab example results

Number of cases         29
Data as input -
Var  1      Var  2      Var  1      Var  2      Var  1      Var  2
350.0        47.0       550.0        95.0       380.0       211.0
510.0       122.0      1270.0       530.0       300.0        38.0
2630.0       278.0       810.0       309.0       140.0        75.0
450.0        43.0      2280.0       407.0       250.0       142.0
540.0        89.0       720.0       159.0        90.0        35.0
480.0       103.0       180.0        78.0      3160.0       969.0
220.0       120.0       860.0       333.0       300.0        73.0
1460.0       147.0       400.0        30.0       620.0       100.0
120.0        55.0       780.0       145.0       230.0       101.0
1070.0       468.0       160.0        86.0

No. of valid cases      29

Variable 1                    Variable 2
Mean                     734.8                         185.8
Minimum                   90.0                          30.0
Maximum                 3160.0                         969.0
Standard deviation       765.2                         201.1
Sum of squares      16395924.1                     1131860.8
Sum of weights                        29.0000
Sum of products                  3483048.9655
Correlation                            0.8085
```