NAG Library Function Document

nag_summary_stats_1var (g01aac)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

+− 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1 Purpose

nag_summary_stats_1var (g01aac) calculates the mean, standard deviation, coefficients of skewness and kurtosis, and the maximum and minimum values for a set of ungrouped data. Weighting may be used.

2 Specification

#include <nag.h>

#include <nagg01.h>

void	nag_summary_stats_1var (Integer n, const double x[], const double wt[], Integer nvalid, double xmean, double xsd, double xskew, double xkurt, double xmin, double xmax, double wsum, NagError *fail)

3 Description

The data consist of a single sample of

n

observations, denoted by

x_{i}

, with corresponding weights,

w_{i}

, for

i = 1, 2, \dots, n

If no specific weighting is required, then each

w_{i}

is set to

1

The quantities computed are:

(a)

The sum of the weights

W = \sum_{i = 1}^{n} w_{i} .

(b)

Mean

\bar{x} = \frac{\sum_{i = 1}^{n} w_{i} x_{i}}{W} .

(c)

Standard deviation

s_{2} = \sqrt{\frac{\sum_{i = 1}^{n} w_{i} {(x_{i} - \bar{x})}^{2}}{d}},   where d = W - \frac{\sum_{i = 1}^{n} w_{i}^{2}}{W} .

(d)

Coefficient of skewness

s_{3} = \frac{\sum_{i = 1}^{n} w_{i} {(x_{i} - \bar{x})}^{3}}{d \times s_{2}^{3}} .

(e)

Coefficient of kurtosis

s_{4} = \frac{\sum_{i = 1}^{n} w_{i} {(x_{i} - \bar{x})}^{4}}{d \times s_{2}^{4}} - 3 .

(f)

Maximum and minimum elements of the sample.

(g)

The number of observations for which

w_{i} > 0

, i.e., the number of valid observations. Suppose

m

observations are valid, then the quantities in (c), (d) and (e) will be computed if

m \geq 2

, and will be based on

m - 1

degrees of freedom. The other quantities are evaluated provided

m \geq 1

4 References

None.

5 Arguments

1: n – IntegerInput: On entry: $n$ , the number of observations.

Constraint: $n \geq 1$ .
2: x[n] – const doubleInput: On entry: the sample observations, $x_{i}$ , for $i = 1, 2, \dots, n$ .
3: wt[n] – const doubleInput: On entry: if weights are being supplied then the elements of wt must contain the weights associated with the observations, $w_{i}$ , for $i = 1, 2, \dots, n$ .
If weights are not supplied then wt must be set to NULL.
4: nvalid – Integer *Output: On exit: is used to indicate the number of valid observations, $m$ ; see Section 3 (g).
5: xmean – double *Output: On exit: the mean, $\bar{x}$ .
6: xsd – double *Output: On exit: the standard deviation, $s_{2}$ .
7: xskew – double *Output: On exit: the coefficient of skewness, $s_{3}$ .
8: xkurt – double *Output: On exit: the coefficient of kurtosis, $s_{4}$ .
9: xmin – double *Output: On exit: the smallest value in the sample.
10: xmax – double *Output: On exit: the largest value in the sample.
11: wsum – double *Output: On exit: the sum of the weights in the array wt, that is $\sum_{i = 1}^{n} w_{i}$ . This will be $n$ if weighted estimates are not used.
12: fail – NagError *Input/Output: The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_BAD_PARAM: On entry, argument $⟨value⟩$ had an illegal value.
NE_CASES_ONE: The number of valid cases is one. The standard deviation and coefficients of skewness and of kurtosis cannot be calculated.
NE_CASES_ZERO: The number of valid cases is zero.
NE_INT_ARG_LE: On entry, $n = ⟨value⟩$ .
Constraint: $n \geq 1$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_REAL_ARG_LT: On entry, $wt [⟨value⟩] = ⟨value⟩$ .
Constraint: $wt [⟨value⟩] \geq 0.0$ .

7 Accuracy

The method used is believed to be stable.

8 Parallelism and Performance

Not applicable.

9 Further Comments

The time taken by nag_summary_stats_1var (g01aac) is approximately proportional to

n

10 Example

This example summarises an (optionally weighted) dataset and displays the results.

NAG Library Function Documentnag_summary_stats_1var (g01aac)