naginterfaces.library.nonpar.randtest_​runs

naginterfaces.library.nonpar.randtest_runs(cl, x, m, nruns, ncount, comm)

randtest_runs performs a runs up (or a runs down) test on a sequence of observations.

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

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g08/g08eaf.html

Parameters

clstr, length 1

Must specify the type of call to randtest_runs.

$cl=\text{'S'}$

This is the one and only call to randtest_runs (single call mode). All data are to be input at once. All test statistics are computed after the counting of runs is complete.

$cl=\text{'F'}$

This is the first call to the function. All initializations are carried out and the counting of runs begins. The final test statistics are not computed since further calls will be made to randtest_runs.

$cl=\text{'I'}$

This is an intermediate call during which the counts of runs are updated. The final test statistics are not computed since further calls will be made to randtest_runs.

$cl=\text{'L'}$

This is the last call to randtest_runs. The test statistics are computed after the final counting of runs is completed.

xfloat, array-like, shape $\left(n\right)$

The sequence of observations.

mint

The maximum number of runs to be sought. If $m\le 0$ then no limit is placed on the number of runs that are found.

$m$ must not be changed between calls to randtest_runs.

nrunsint

If $cl=\text{'S'}$ or $\text{'F'}$, $nruns$ need not be set.

If $cl=\text{'I'}$ or $\text{'L'}$, $nruns$ must contain the value returned by the previous call to randtest_runs.

ncountint, array-like, shape $\left(\text{maxr}\right)$

If $cl=\text{'S'}$ or $\text{'F'}$, $ncount$ need not be set.

If $cl=\text{'I'}$ or $\text{'L'}$, $ncount$ must contain the values returned by the previous call to randtest_runs.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

Returns

nrunsint

The number of runs actually found.

ncountint, ndarray, shape $\left(\text{maxr}\right)$

The counts of runs of the different lengths, $c_{\text{i}}$, for $\text{i}=1,2,\dots ,r$.

exfloat, ndarray, shape $\left(\text{maxr}\right)$

If $cl=\text{'S'}$ or $\text{'L'}$, (i.e., if it is the final exit) then $ex$ contains the expected values of the counts, $e_{\text{i}}$, for $\text{i}=1,2,\dots ,r$.

Otherwise the elements of $ex$ are not set.

covfloat, ndarray, shape $(\text{maxr},\text{maxr})$

If $cl=\text{'S'}$ or $\text{'L'}$ (i.e., if it is the final exit) then $cov$ contains the covariance matrix of the counts, ${\Sigma }_c$.

Otherwise the elements of $cov$ are not set.

chifloat

If $cl=\text{'S'}$ or $\text{'L'}$ (i.e., if it is the final exit), $chi$ contains the approximate ${\chi }^2$ test statistic, $X^2$.

Otherwise $chi$ is not set.

dffloat

If $cl=\text{'S'}$ or $\text{'L'}$ (i.e., if it is the final exit) then $df$ contains the degrees of freedom of the ${\chi }^2$ statistic.

Otherwise $df$ is not set.

probfloat

If $cl=\text{'S'}$ or $\text{'L'}$, (i.e., if it is the final exit) then $prob$ contains the upper tail probability corresponding to the ${\chi }^2$ test statistic, i.e., the significance level.

Otherwise $prob$ is not set.

Raises

NagValueError

(errno $1$)

On entry, $cl=⟨value⟩$.

Constraint: $cl=\text{'S'}$, $\text{'F'}$, $\text{'I'}$ or $\text{'L'}$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: if $cl=\text{'S'}$, $n\ge 3$, otherwise $n\ge 1$.

(errno $3$)

On entry, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: if $cl=\text{'S'}$, $m\le n$.

(errno $4$)

On entry, $\text{maxr}=⟨value⟩$ and $n=⟨value⟩$.

Constraint: if $cl=\text{'S'}$, $\text{maxr}<n$.

(errno $4$)

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

Constraint: $\text{maxr}\ge 1$.

(errno $7$)

There is a tie in the sequence of observations.

(errno $8$)

The total length of the runs found is less than $\text{maxr}$.

$\text{maxr}=⟨value⟩$ whereas the total length of all runs is $⟨value⟩$.

(errno $9$)

The covariance matrix stored in $cov$ is not positive definite, thus the approximate ${\chi }^2$ test statistic cannot be computed.

This may be because $\text{maxr}$ is too large relative to the length of the full sequence.

Warns

NagAlgorithmicWarning

(errno $10$)

The number of runs requested were not found, only $⟨value⟩$ out of the requested $⟨value⟩$ where found.

All statistics are returned and may still be of use.

Notes

Runs tests may be used to investigate for trends in a sequence of observations. randtest_runs computes statistics for the runs up test. If the runs down test is desired then each observation must be multiplied by $-1$ before randtest_runs is called with the modified vector of observations. randtest_runs may be used in two different modes:

1. a single call to randtest_runs which computes all test statistics after counting the runs;

2. multiple calls to randtest_runs with the final test statistics only being computed in the last call.

The second mode is necessary if all the data do not fit into the memory. See argument $cl$ in Parameters for details on how to invoke each mode.

A run up is a sequence of numbers in increasing order. A run up ends at $x_k$ when $x_k>x_{k+1}$ and the new run then begins at $x_{k+1}$. randtest_runs counts the number of runs up of different lengths. Let $c_{\text{i}}$ denote the number of runs of length $\text{i}$, for $\text{i}=1,2,\dots ,r-1$. The number of runs of length $r$ or greater is then denoted by $c_r$.

An unfinished run at the end of a sequence is not counted unless the sequence is part of an initial or intermediate call to randtest_runs (i.e., unless there is another call to randtest_runs to follow) in which case the unfinished run is used together with the beginning of the next sequence of numbers input to randtest_runs in the next call. The following is a trivial example.

Suppose we called randtest_runs twice with the following two sequences:

($0.20$ $0.40$ $0.45$ $0.40$ $0.15$ $0.75$ $0.95$ $0.23$) and

($0.27$ $0.40$ $0.25$ $0.10$ $0.34$ $0.39$ $0.61$ $0.12$).

Then after the second call randtest_runs would have counted the runs up of the following lengths:

$3$, $1$, $3$, $3$, $1$, and $4$.

When the counting of runs is complete randtest_runs computes the expected values and covariances of the counts, $c_i$. For the details of the method used see Knuth (1981). An approximate ${\chi }^2$ statistic with $r$ degrees of freedom is computed, where

$$X^2={(c-{\mu }_c)}^T{\Sigma }_c^{-1}(c-{\mu }_c)\text{,}$$

where

$c$ is the vector of counts, $c_{\text{i}}$, for $\text{i}=1,2,\dots ,r$,

${\mu }_c$ is the vector of expected values,

$e_{\text{i}}$, for $\text{i}=1,2,\dots ,r$, where $e_i$ is the expected value for $c_i$ under the null hypothesis of randomness, and

${\Sigma }_c$ is the covariance matrix of $c$ under the null hypothesis.

The use of the ${\chi }^2$-distribution as an approximation to the exact distribution of the test statistic, $X^2$, improves as the length of the sequence relative to $m$ increases and hence the expected value, $e$, increases.

You may specify the total number of runs to be found. If the specified number of runs is found before the end of a sequence randtest_runs will exit before counting any further runs. The number of runs actually counted and used to compute the test statistic is returned via $nruns$.

References

Dagpunar, J, 1988, Principles of Random Variate Generation, Oxford University Press

Knuth, D E, 1981, The Art of Computer Programming (Volume 2), (2nd Edition), Addison–Wesley

Morgan, B J T, 1984, Elements of Simulation, Chapman and Hall

Ripley, B D, 1987, Stochastic Simulation, Wiley