## Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

## random-test

Some simple randomness tests for a sequence of numbers.

## Usage

(require-extension random-test)

## Documentation

The `random-test` library provides a procedure that applies various statistical tests to a sequence of random numerical values, and a procedure to reports the results of those tests in convenient form.

The library is useful for evaluating pseudorandom number generators for statistical sampling applications, compression algorithms, and other applications where the properties of a random sequence are of interest. The code in the library is based on the ent program by John Walker.

### Procedures

*[procedure]*

`make-random-test:: [CAR CDR NULL?] -> (SEQ -> RANDOM-STATS)`

This procedure creates a procedure that reads in a sequence of numerical values, and performs statistical tests to tests the randomness of the elements of the sequence.

By default, the sequence is expected to be a list; however, if a different sequential data structure is used (e.g. a stream), the optional arguments `CAR, CDR, NULL?` may be used to specify procedures that perform the corresponding operations on the input sequence.

The returned procedure is of the form `SEQ -> RANDOM-STATS`, where `SEQ` is the sequence and the returned value is an alist with the following fields:

`chisq`- the result of the Chi-Square test
`pochisq`- the calculated probability of the Chi-Square test
`mean`- the mean of the values in the input sequence</td></tr>
`min`- the minimum of the values in the input sequence</td></tr>
`max`- the maximum of the values in the input sequence</td></tr>
`montepi`- Monte Carlo value of pi
`scc`- the serial correlation coefficient

See the following section for explanation of the different fields.

*[procedure]*

`format-random-stats:: OUT * RANDOM-STATS -> UNDEFINED`

Given an output port, and the value returned by the random test procedure, this procedure outputs a human readable interpretation of the test results.

### Tests

#### Chi-Square Test

In general, the Chi-Square distribution for an experiment with `k` possible outcomes, performed `n` times, in which `Y1, Y2,... Yk` are the number of experiments which resulted in each possible outcome, and probabilities of each outcome `p1, p2,... pk`, is given as:

\chi^{2} = \sum_{1 <= i <= k}{\frac{(Y_{i} - m p_{i})^{2}}{np_{i}}}

`\Chi^2` will grow larger as the measured results diverge from those expected by pure chance. The probability `Q` that a Chi-Square value calculated for an experiment with d degrees of freedom (where `d=k-1`, one less the number of possible outcomes) is due to chance is:

Q(\Chi^2,d) = [2^{d/2} * \Gamma(d/2)]^{-1} * \int_{\Chi^2}^{\infty}(t)^{d/2-1} * exp(-t/2) * dt

Where Gamma is the generalization of the factorial function to real and complex arguments:

\Gamma(x) = \int_{0}^{\infty} t^{x-1} * exp(-t) * dt

There is no closed form solution for Q, so it must be evaluated numerically. Note that the probability calculated from the `\Chi^2` is an approximation which is valid only for large values of n, and is therefore only meaningful when calculated from a large number of independent experiments.

In this implementation, the Chi-Square distribution is calculated for the list of values given as argument to the random-test procedure and expressed as an absolute number and a percentage which indicates how frequently a truly random sequence would exceed the value calculated.

The percentage can be interpreted as the degree to which the sequence tested is suspected of being non-random. If the percentage is greater than 99% or less than 1%, the sequence is almost certainly not random. If the percentage is between 99% and 95% or between 1% and 5%, the sequence is suspect. Percentages between 90% and 95% and 5% and 10% indicate the sequence is almost suspect.

#### Arithmetic Mean

This is simply the result of summing the all the values in the sequence and dividing by the sequence length. If the data are close to random, the mean should be about `(2^b - 1)/2` where `b` is the number of bits used to represent a value. If the mean departs from this value, the values are consistently high or low.

#### Monte Carlo Value for Pi

Each pair of two values in the input sequence is used as X and Y coordinates within a square with side N (the length of the input sequence). If the distance of the randomly-generated point is less than the radius of a circle inscribed within the square, the pair of values is considered a hit. The percentage of hits can be used to calculate the value of pi:

# points within circle 1/4 * pi * r^2 ---------------------- = -------------- = 1/4 * pi # points within square r^2

Therefore,

# points within circle pi = 4 * ---------------------- # points within square

For very long sequences (this approximation converges very slowly), the value will approach the correct value of Pi if the sequence is close to random.

#### Serial Correlation Coefficient

This quantity measures the extent to which each value in the sequence depends upon the previous value. For random sequences, this metric (which can be positive or negative) will be close to zero. A non-random sequence such as a text file will yield a serial correlation coefficient of about 0.5. Predictable data will exhibit serial correlation coefficients approaching 1.

## Examples

(use random-test srfi-1) (randomize (current-milliseconds)) (define random-test (make-random-test)) (define lst (list-tabulate 1000000 (lambda (x) (random 1000000)))) (random-test lst 1000000) (define stats (random-test lst 1000000)) (format-random-stats stats)

## About this egg

### Author

### Version history

- 1.9
- Eliminated easyffi dependency
- 1.8
- Documentation converted to wiki format
- 1.7
- Ported to Chicken 4
- 1.6
- Removed testeez dependency
- 1.5
- Build script updated for better cross-platform compatibility
- 1.4
- eggdoc documentation fix
- 1.3
- License upgrade to GPL v3.
- 1.2
- Simplified the interface of random-test procedure
- 1.1
- Bug fix in the bin update code
- 1.0
- Initial release

### Requirements

`easyffi`

### License

Copyright 2007-2012 Ivan Raikov. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A full copy of the GPL license can be found at <http://www.gnu.org/licenses/>.