NAG Library Routine Document

g01abf (summary_2var)

1
Purpose

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

2
Specification

Fortran Interface
Subroutine g01abf ( n, x1, x2, iwt, wt, res, ifail)
Integer, Intent (In):: n
Integer, Intent (Inout):: iwt, ifail
Real (Kind=nag_wp), Intent (In):: x1(n), x2(n)
Real (Kind=nag_wp), Intent (Inout):: wt(n)
Real (Kind=nag_wp), Intent (Out):: res(13)
C Header Interface
#include <nagmk26.h>
void  g01abf_ (const Integer *n, const double x1[], const double x2[], Integer *iwt, double wt[], double res[], Integer *ifail)

3
Description

The data consist of two samples of n observations, denoted by xi, and yi, for i=1,2,,n, with corresponding weights wi, for i=1,2,,n.
If no specific weighting is given, then each wi is set to 1.0 in g01abf.
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 wi>0, i.e., the number of valid observations. The quantities in (d) and (e) above will only be computed if m2. All other items are computed if m1.

4
References

None.

5
Arguments

1:     n – IntegerInput
On entry: n, the number of pairs of observations.
Constraint: n1.
2:     x1n – Real (Kind=nag_wp) arrayInput
On entry: the observations from the first sample, xi, for i=1,2,,n.
3:     x2n – Real (Kind=nag_wp) arrayInput
On entry: the observations from the second sample, yi, for i=1,2,,n.
4:     iwt – IntegerInput/Output
On entry: indicates whether user-supplied weights are provided by you:
iwt=1 
  • Indicates that user-supplied weights are given in the array wt.
iwt0 
  • Indicates that user-supplied weights are not given. In this case the routine assigns the value 1.0 to each element of the weight array, wt.
On exit: is used to indicate the number of valid observations, m; see Section 3(g), above.
5:     wtn – Real (Kind=nag_wp) arrayInput/Output
On entry: if weights are being supplied then the elements of wt must contain the weights associated with the observations, wi, for i=1,2,,n.
Constraint: if iwt=1, wti0.0, for i=1,2,,n.
On exit: if iwt=1, the elements of wt are unchanged, otherwise each element of wt will be assigned the value 1.0.
6:     res13 – Real (Kind=nag_wp) arrayOutput
On exit: the elements of res contain the following results:
res1 mean of the first sample, x-;
res2 mean of the second sample, y-;
res3 standard deviation of the first sample, s1;
res4 standard deviation of the second sample, s2;
res5 corrected sum of squares of the first sample, c11;
res6 corrected sum of products of the two samples, c12;
res7 corrected sum of squares of the second sample, c22;
res8 product-moment correlation coefficient, R;
res9 minimum of the first sample;
res10 maximum of the first sample;
res11 minimum of the second sample;
res12 maximum of the second sample;
res13 sum of weights, i=1nwi (=n, if iwt=0, on entry).
7:     ifail – IntegerInput/Output
On entry: ifail must be set to 0, -1 or 1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1 or 1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6
Error Indicators and Warnings

If on entry 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:
ifail=1
On entry, n=value.
Constraint: n1.
ifail=2
The number of valid cases, m, is 1. In this case standard deviation and product-moment correlation coefficient cannot be calculated.
ifail=3
On entry, wtvalue=value.
Constraint: wti0.0, for i=1,2,,n 
The number of valid cases, m, is 0.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7
Accuracy

The method used is believed to be stable.

8
Parallelism and Performance

g01abf is not threaded in any implementation.

9
Further Comments

The time taken by g01abf increases linearly with n.

10
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 g01abf, all the calculated quantities are printed. In the example, there is one set of data, with 29 (unweighted) pairs of observations.

10.1
Program Text

Program Text (g01abfe.f90)

10.2
Program Data

Program Data (g01abfe.d)

10.3
Program Results

Program Results (g01abfe.r)