naginterfaces.library.stat.summary_​onevar

naginterfaces.library.stat.summary_onevar(x, wt=None, pn=0, rcomm=None)

summary_onevar calculates the mean, standard deviation, coefficients of skewness and kurtosis, and the maximum and minimum values for a set of (optionally weighted) data. The input data can be split into arbitrary sized blocks, allowing large datasets to be summarised.

For full information please refer to the NAG Library document for g01at

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g01/g01atf.html

Parameters

xfloat, array-like, shape $\left(\text{nb}\right)$

The current block of observations, corresponding to $x_{\text{i}}$, for $\text{i}=k+1,\dots ,k+b$, where $k$ is the number of observations processed so far and $b$ is the size of the current block of data.

wtNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $wt\text{is not}None$: $\text{nb}$; otherwise: $0$.

If $wt$ is not None, $wt$ must contain the user-supplied weights corresponding to the block of data supplied in $x$, that is $w_{\text{i}}$, for $\text{i}=k+1,\dots ,k+b$.

If $wt$ is None, $w_i=1$ for all $i$.

pnint, optional

The number of valid observations processed so far, that is the number of observations with $w_i>0$, for $\text{i}=1,2,\dots ,k$. On the first call to summary_onevar, or when starting to summarise a new dataset, $pn$ must be set to $0$.

If $pn\ne 0$, it must be the same value as returned by the last call to summary_onevar.

rcommNone or float, ndarray, shape $(:)$, optional, modified in place

Note: the required length for this argument is determined as follows: if $rcomm\text{is not}None$: $20$; otherwise: $0$.

Optionally, on entry: communication array, used to store information between calls to summary_onevar. If $pn=0$, $rcomm$ need not be initialized, otherwise it must be unchanged since the last call to this function.

If $rcomm$ is None, $rcomm$ is not referenced and all the data must be supplied in one go.

On exit, if not None on entry: the updated communication array. The first five elements of $rcomm$ hold information that may be of interest with

$$\begin{array}{c}\begin{array}{ccc}rcomm\left[0\right]& =& {\sum }_1^{k+b}{w}_i\\ rcomm\left[1\right]& =& {\left({\sum }_1^{k+b}{w}_i\right)}^2-{\sum }_1^{k+b}{w}_i^2\\ rcomm\left[2\right]& =& {\sum }_1^{k+b}{w}_i{(x_i-\overline{x})}^2\\ rcomm\left[3\right]& =& {\sum }_1^{k+b}{w}_i{(x_i-\overline{x})}^3\\ rcomm\left[4\right]& =& {\sum }_1^{k+b}{w}_i{(x_i-\overline{x})}^4\end{array}\end{array}$$

the remaining elements of $rcomm$ are used for workspace and so are undefined.

Returns

pnint

The updated number of valid observations processed, that is the number of observations with $w_i>0$, for $\text{i}=1,2,\dots ,k+b$.

xmeanfloat

$\overline{x}$, the mean of the first $k+b$ observations.

xsdfloat

$s_2$, the standard deviation of the first $k+b$ observations.

xskewfloat

$s_3$, the coefficient of skewness for the first $k+b$ observations.

xkurtfloat

$s_4$, the coefficient of kurtosis for the first $k+b$ observations.

xminfloat

The smallest value in the first $k+b$ observations.

xmaxfloat

The largest value in the first $k+b$ observations.

Raises

NagValueError

(errno $11$)

On entry, $\text{nb}=⟨value⟩$.

Constraint: $\text{nb}\ge 0$.

(errno $41$)

On entry, $wt[⟨value⟩]=⟨value⟩$.

Constraint: if $wt\text{is not}None$ then $wt[\text{i}-1]\ge 0$, for $\text{i}=1,2,\dots ,\text{nb}$.

(errno $51$)

On entry, $pn=⟨value⟩$.

Constraint: $pn\ge 0$.

(errno $52$)

On entry, $pn=⟨value⟩$.

On exit from previous call, $pn=⟨value⟩$.

Constraint: if $pn>0$, $pn$ must be unchanged since previous call.

(errno $54$)

On entry, $pn=⟨value⟩$.

Constraint: if $rcomm\text{is}None$ then $pn=0$.

(errno $121$)

$rcomm$ has been corrupted between calls.

Warns

NagAlgorithmicWarning

(errno $53$)

On entry, the number of valid observations is zero.

(errno $71$)

On exit we were unable to calculate $xskew$ or $xkurt$. A value of $0$ has been returned.

(errno $72$)

On exit we were unable to calculate $xsd$, $xskew$ or $xkurt$. A value of $0$ has been returned.

Notes

Given a sample of $n$ observations, denoted by $x=\{x_i:i=1,2,\dots ,n\}$ and a set of non-negative weights, $w=\{w_i:i=1,2,\dots ,n\}$, summary_onevar calculates a number of quantities:

1. Mean

   $$\overline{x}=\frac{{\sum }_1^n{w}_i{x}_i}{W}\text{, where}W=\sum _1^n{w}_i\text{.}$$

2. Standard deviation

   $$s_2=\sqrt{\frac{{\sum }_1^n{w}_i{(x_i-\overline{x})}^2}{d}}\text{, where}d=W-\frac{{\sum }_1^n{w}_i^2}{W}\text{.}$$

3. Coefficient of skewness

   $$s_3=\frac{{\sum }_1^n{w}_i{(x_i-\overline{x})}^3}{d{s}_2^3}\text{.}$$

4. Coefficient of kurtosis

   $$s_4=\frac{{\sum }_1^n{w}_i{(x_i-\overline{x})}^4}{d{s}_2^4}-3\text{.}$$

5. Maximum and minimum elements, with $w_i\ne 0$.

These quantities are calculated using the one pass algorithm of West (1979).

For large datasets, or where all the data is not available at the same time, $x$ and $w$ can be split into arbitrary sized blocks and summary_onevar called multiple times.

References

West, D H D, 1979, Updating mean and variance estimates: An improved method, Comm. ACM (22), 532–555