(use eggdoc) (define doc `((eggdoc:begin (name "random-test") (description "Some simple randomness tests for a sequence of numbers.") (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov")) (history (version "1.7" "Ported to Chicken 4") (version "1.6" "Removed testeez dependency") (version "1.5" "Build script updated for better cross-platform compatibility") (version "1.4" "eggdoc documentation fix") (version "1.3" "License upgrade to GPL v3.") (version "1.2" "Simplified the interface of random-test procedure") (version "1.1" "Bug fix in the bin update code") (version "1.0" "Initial release")) (requires easyffi) (usage "(require-extension random-test)") (download "random-test.egg") (documentation (p "The " (tt "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. ") (p "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 " (url "http://www.fourmilab.ch/random/" "ent program") " by John Walker.") (subsection "Procedures" (procedure "make-random-test:: [CAR CDR NULL?] -> (SEQ -> RANDOM-STATS)" (p "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.") (p "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 " (tt "CAR, CDR, NULL?") " may be used to " "specify procedures that perform the corresponding operations on " "the input sequence. ") (p "The returned procedure is of the form " (tt "SEQ -> RANDOM-STATS") ", where " (tt "SEQ") " is the sequence and the returned value is an " "alist with the following fields: " (symbol-table (describe "'ent" "entropy measure") (describe "'chisq" "the result of the Chi-Square test (see next section)") (describe "'pochisq" "the calculated probability of the Chi-Square test (see next section)") (describe "'mean" "the mean of the values in the input sequence") (describe "'min" "the minimum of the values in the input sequence") (describe "'max" "the maximum of the values in the input sequence") (describe "'montepi" "Monte Carlo value of pi (see next section)") (describe "'scc" "the serial correlation coefficient (see next section)")))) (procedure "format-random-stats:: OUT * RANDOM-STATS -> UNDEFINED" (p "Given an output port, and the value returned by the random test " "procedure, this procedure outputs a human readable interpretation " "of the test results."))) (subsection "Tests" (ol (li "Chi-Square Test" (p "In general, the Chi-Square distribution for an experiment with " (tt "k") " possible outcomes, performed " (tt "n") " times, " "in which " (tt "Y1, Y2,... Yk") " are the number of experiments " "which resulted in each possible outcome, and probabilities of each " "outcome " (tt "p1, p2,... pk")", is given as: " (img (@ (src "random-test.fig1.png") (alt "\\chi^{2} = \\sum_{1 <= i <= k}{\\frac{(Y_{i} - m p_{i})^{2}}{np_{i}}}")))) (p (tt "\\Chi^2") " will grow larger as the measured results diverge from those " "expected by pure chance. The probability " (tt "Q") " that a Chi-Square value " "calculated for an experiment with d degrees of freedom (where " (tt "d=k-1") ", one less the number of possible outcomes) is due to chance is: " (img (@ (src "random-test.fig2.png") (alt "Q(\\Chi^2,d) = [2^{d/2} * \\Gamma(d/2)]^{-1} * \\int_{\\Chi^2}^{\\infty}(t)^{d/2-1} * exp(-t/2) * dt")))) (p "Where Gamma is the generalization of the factorial function to real " "and complex arguments: " (img (@ (src "random-test.fig3.png") (alt "\\Gamma(x) = \\int_{0}^{\\infty} t^{x-1} * exp(-t) * dt")))) (p "There is no closed form solution for Q, so it must be evaluated " "numerically. Note that the probability calculated from the " (tt "\\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. ") (p "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. ") (p "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.")) (li "Arithmetic Mean" (p "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 " (tt "(2^b - 1)/2") " where " (tt "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.")) (li "Monte Carlo Value for Pi" (p "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: " (pre #<.")))) (if (eggdoc->html doc) (void))