runstest

Run test for randomness

Syntax

h = runstest(x)

h = runstest(x,v)

h = runstest(x,'ud')

h = runstest(___,Name,Value)

[h,p,stats] = runstest(___)

Description

h = runstest(x) returns a test decision for the null hypothesis that the values in the data vector x come in random order, against the alternative that they do not. The test is based on the number of runs of consecutive values above or below the mean of x. The result h is 1 if the test rejects the null hypothesis at the 5% significance level, or 0 otherwise.

h = runstest(x,v) returns a test decision based on the number of runs of consecutive values above or below the specified reference value v. Values exactly equal to v are discarded.

h = runstest(x,'ud') returns a test decision based on the number of runs up or down. Too few runs indicate a trend, while too many runs indicate an oscillation. Values exactly equal to the preceding value are discarded.

h = runstest(___,Name,Value) returns a test decision using additional options specified by one or more name-value pair arguments. For example, you can change the significance level of the test, specify the algorithm used to calculate the p-value, or conduct a one-sided test.

[h,p,stats] = runstest(___) also returns the p-value of the test p, and a structure stats containing additional data about the test.

Examples

Test Data for Randomness Using Sample Median

Generate a vector of 40 random numbers from a standard normal distribution.

rng default;  % for reproducibility
x = randn(40,1);

Test whether the values in x appear in random order, using the sample median as the reference value.

[h,p] = runstest(x,median(x))

h = 
0

p = 
0.8762

The returned value of h = 0 indicates that runstest does not reject the null hypothesis that the values in x are in random order at the default 5% significance level.

Input Arguments

x — Data vector

vector of scalar values

Data vector, specified as a vector of scalar values. runstest treats NaN values in x as missing values, and ignores them.

Data Types: single | double

v — Reference value

mean of x (default) | scalar value

Reference value, specified as a scalar value. If you specify a value for v, then runstest performs the hypothesis test based on the number of runs of consecutive values above or below v. runstest discards values exactly equal to v.

Data Types: single | double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Alpha',0.01,'Method','Approximate','Tail','right' specifies a right-tailed test with 1% significance level, which returns the approximate p-value.

Alpha — Significance level

0.05 (default) | scalar value in the range (0,1)

Significance level of the hypothesis test, specified as the comma-separated pair consisting of 'Alpha' and a scalar value in the range (0,1).

Example: 'Alpha',0.01

Data Types: single | double

Method — Method used to compute p-value

'exact' | 'approximate'

Method used to compute p-value, specified as the comma-separated pair consisting of 'Method' and either 'exact' to use an exact algorithm, or 'approximate' to use a normal approximation. The default is 'exact' for runs above/below, and for runs up/down when the length of x is less than or equal to 50. If runstest tests for runs up/down and the length of x is greater than 50, then the default is 'approximate', and the 'exact' method is not available.

Example: 'Method','approximate'

Tail — Type of alternative hypothesis

'both' (default) | 'right' | 'left'

Type of alternative hypothesis, specified as the comma-separated pair consisting of 'Tail' and one of the following.

'both'	Two-tailed test (sequence is not random)
'right'	Right-tailed test (like values separate for runs above/below, direction alternates for runs up/down)
'left'	Left-tailed test (like values cluster for runs above/below, values trend for runs up/down)

Example: 'Tail','right'

Output Arguments

h — Hypothesis test result

1 | 0

Hypothesis test result, returned as 1 or 0.

• If h = 1, then runstest rejects the null hypothesis at the Alpha significance level.

• If h = 0, then runstest fails to reject the null hypothesis at the Alpha significance level.

The result in runstest is based on the number of runs of consecutive values above or below the mean of x. Too few runs indicate a tendency for high and low values to cluster. Too many runs indicate a tendency for high and low values to alternate.

runstest uses a test statistic which is the difference between the number of runs and its mean, divided by its standard deviation. The test statistic is approximately normally distributed when the null hypothesis is true.

p — p-value

scalar value in the range [0,1]

p-value of the test, returned as a scalar value in the range [0,1]. p is the probability of observing a test statistic as extreme as, or more extreme than, the observed value under the null hypothesis. Small values of p cast doubt on the validity of the null hypothesis.

p is computed from either the test statistic or the exact distribution of the number of runs, depending on the value specified for the 'Method' name-value pair argument.

stats — Test data

structure

Test data, returned as a structure with the following fields.

• nruns — The number of runs

• n1 — The number of values above v

• n0 — The number of values below v

• z — The test statistic

References

[1] Gibbons, Jean Dickinson, and Subhabrata Chakraborti. Nonparametric Statistical Inference. 5th ed. Boca Raton: CRC Press, 2011.

Version History

Introduced before R2006a