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_ALLOC_FAIL: Dynamic memory allocation failed.
See Section 3.2.1.2 in the Essential Introduction for further information.
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.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.
NE_NO_LICENCE: Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.
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)