1 Random Distributions

(require (planet cce/fasttest:4:1/random))

This module provides utilities for generating random values.

1.1 Booleans

p : (prob/c 0 1) = 1/2

Produces #t with probability p, and f with probability (- 1 p).

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean)))
'(#f #f #t #f #f #f #t #t #f #f #t #f #f #f #t #t #t #f #t #f)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean 1/4)))
'(#f #f #t #f #f #f #f #f #f #f #t #f #f #f #t #t #f #f #t #f)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean 3/4)))
'(#t #f #t #f #f #f #t #t #t #t #t #f #t #t #t #t #t #t #t #t)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean 0)))
'(#f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean 1)))
'(#t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t)

(random-boolean/fair) → boolean?

Produces #t or #f with equal probability.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean/fair)))
'(#f #f #t #f #f #f #t #t #f #f #t #f #f #f #t #t #t #f #t #f)

(random-boolean/bernoulli p) → boolean?

p : (prob/c 0 1)

Produces #t with probability p, and f with probability (- 1 p).

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean/bernoulli 1/4)))
'(#f #f #t #f #f #f #f #f #f #f #t #f #f #f #t #t #f #f #t #f)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean/bernoulli 3/4)))
'(#t #f #t #f #f #f #t #t #t #t #t #f #t #t #t #t #t #t #t #t)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean/bernoulli 0)))
'(#f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f #f)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-boolean/bernoulli 1)))
'(#t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t #t)

1.2 Numbers

(random-natural) → natural-number/c

(random-integer) → exact-integer?

(random-rational) → (and/c rational? exact?)

(random-exact) → (and/c number? exact?)

(random-positive-real) → (and/c inexact-real? positive?)

(random-real) → inexact-real?

(random-inexact) → (and/c number? inexact?)

(random-number) → number?

These procedures represent distributions over various subsets of the Scheme numbers.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural)))
'(679 165 2256 7 60 123 841 886 457 688 1836 37 424 385 1499 2716 748 429 4017 499)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-integer)))
'(-165 7 -123 886 -688 37 -385 2716 429 499 311 580 15 1488 1883 -2622 586 395 354 -3998)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-rational)))
'(-282 -841/887 -918/19 -1499/2717 -4017 311/1750 15/2854 1883 994/587 -2140 -3998/1095 -484/791 668/127 76/1265 1469 117/1783 120 -311 1384 425/2489)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-exact)))
'(-282 -841/887-688/1837i -77/300+374/215i -1302 116/219-2853/1489i 130 586 -2140 -3998/1095-560/969i -908 -37/81 809/801+87/325i 159/1106-1171/125i 1834/1385-1684/213i 438 1893 -983/458 1259/666 161/90-53/1344i -118)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-positive-real)))
'(0.5978373153418373 0.10544079461477066 1.065426214170885 1.0458950820656803 1.2602262735583296 0.16518257759654129 0.9620560311285986 3.379590610653502 0.7268962380113153 0.029612850523509173 0.3713505520196463 0.31048000016794686 0.33976813464024447 0.25512483026381727 1.4252039491595079 12.099866935688016 0.6654006959406588 0.46671715760029037 0.16743681623180834 35.09364653846772)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-real)))
'(-8.102437753519679 -1.065426214170885 0.6509199604883179 -0.16518257759654129 -3.048733385695219 0.7268962380113153 2.2319350685211328 -0.31048000016794686 17.11158384560407 1.4252039491595079 -0.19605918316666343 -0.46671715760029037 1.0916879815729899 0.6418003318571719 -1.8476783856271501 -0.7860292236838364 -1.4853973411518142 -0.05042955540346871 0.29858213102621484 5.290089668540595)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-inexact)))
'(-0.10544079461477066-2.0510232372278656i -3.155542799752904 -3.048733385695219+0.7268962380113153i -0.3713505520196463 -0.33976813464024447 1.4252039491595079 0.6654006959406588+5.73356799529654i -0.05471776721450147-1.5036082722103665i -0.7860292236838364 -0.6062879125014674+0.9909767946414353i -0.4245243297674075 0.004466544667114087 -1.8803943633190778 16.343777171383724 0.38189045062571664+0.3708481044313414i -0.3492758929334177+1.1122446171095848i -1.290107161461921-0.699963778818598i 0.8022352854604103 -1.3022964694716193 4.1980008775469075-0.9230057775064026i)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-number)))
'(-282-123/842i -688/1837-212/193i 374/215 -1302 1.6719289307759317 1.0418763249943892+12.099866935688016i -1157/396 -442 651 1581/260+668/127i 35.45887271469893 1469/262+117/1783i 40/781-311/943i 576 -2488 -450/577 -108 857 19/2 629/463-2687/2729i)

(random-integer/uniform lo hi) → (integer-in lo hi)

lo : exact-integer?

hi : (and/c exact-integer? (>=/c lo))

Produces an integer chosen uniformly in the range [lo,hi], inclusive.

Examples:
> (build-list 20 (lambda (i) (random-integer/uniform 0 19)))
'(14 17 1 17 6 4 17 5 9 2 18 17 18 6 16 13 9 19 8 3)
> (build-list 20 (lambda (i) (random-integer/uniform -1000 1000)))
'(-506 82 -601 -192 -491 459 -749 219 139 692 305 -261 999 -67 195 48 -572 422 71 602)
> (build-list 20 (lambda (i) (random-integer/uniform 10 10)))
'(10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10)

Note: out-of-order arguments cause an exception!

> (build-list 10 (lambda (i) (random-integer/uniform 1 -1)))
random-integer/uniform: contract violation, expected
<(and/c exact-integer? (>=/c 1))>, given -1, which isn't
(>=/c 1)
  contract from
    /Users/cce/git/planet/fasttest/random.rkt
  blaming program
  contract:
    (->d ((x ...) (y ...)) () (_ ...))
  at: /Users/cce/git/planet/fasttest/random.rkt:81.2

(random-natural/binomial n p) → (integer-in 0 n)

n : natural-number/c

p : (prob/c 0 1)

Produces the number of successes (#t) in n Bernoulli trials with probability p ((random-boolean/bernoulli p)).

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/binomial 20 1/2)))
'(11 9 12 12 10 13 12 11 12 9 9 13 10 3 11 13 7 11 10 6)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/binomial 20 1/4)))
'(5 8 3 7 7 4 2 3 3 5 7 7 5 1 3 5 5 4 7 3)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/binomial 20 3/4)))
'(15 17 15 17 16 16 17 16 16 14 15 15 16 17 15 16 15 15 18 18)

(random-natural/geometric p base) → natural-number/c

p : (prob/c)

base : (one-of/c 0 1)

Produces a natural number from a geometric distribution with minimum value base and mean (+ base (/ (- 1 p) p)). The probability of each possible result n+base is (* p (expt (- 1 p) n)).

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/geometric 1/2 0)))
'(0 0 3 0 0 0 1 1 0 0 2 0 0 0 2 3 1 0 5 0)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/geometric 1/2 1)))
'(1 1 4 1 1 1 2 2 1 1 3 1 1 1 3 4 2 1 6 1)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/geometric 1/10 0)))
'(6 1 21 0 0 1 7 8 4 6 17 0 4 3 14 25 7 4 38 4)

(random-natural/pascal n p) → natural-number/c

n : exact-positive-integer?

p : (prob/c)

Produces the sum of n geometric natural numbers based on probability p ((random-natural/geometric p 0)).

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/pascal 10 1/2)))
'(5 8 13 11 12 8 14 11 16 6 11 8 8 5 6 10 6 14 7 5)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/pascal 10 1/10)))
'(48 80 114 97 109 71 108 104 129 66 98 63 70 64 65 87 65 116 65 59)

(random-natural/poisson r) → natural-number/c

r : (and rational? positive?)

Produces a natural number with a Poisson distribution, meaning the number of events occurring in a unit of time if the events occur independently and with an average rate of r per unit of time.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/poisson 1)))
'(2 3 1 1 3 0 1 0 1 1 1 1 0 0 0 1 1 0 1 2)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/poisson 10)))
'(14 6 7 9 12 8 8 6 11 8 14 11 13 9 6 13 10 8 10 8)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-natural/poisson 100)))
'(111 102 114 105 105 111 102 83 90 104 81 116 85 110 106 102 88 94 88 91)

(random-integer/skellam r1 [r2]) → exact-integer?

r1 : (and rational? positive?)

r2 : (and rational? positive?) = r1

Produces the difference between two Poisson random variables, chosen with rates r1 and r2 respectively.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-integer/skellam 10)))
'(8 -2 4 2 3 3 4 -7 2 2 -5 8 4 -7 -3 1 -2 7 2 9)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-integer/skellam 10 20)))
'(-5 -8 -7 -6 -2 -19 -15 -12 -8 -9 -3 -9 -10 -5 -12 -6 -11 -11 -17 -11)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-integer/skellam 20 10)))
'(23 9 14 18 9 4 5 22 12 12 13 1 10 8 6 4 14 10 4 15)

(random-real/uniform lo hi) → (real-in lo hi)

lo : real?

hi : (and/c real? (>=/c lo))

Produces an inexact real number from a uniform distribution in the range [lo,hi], inclusive.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-real/uniform -1/2 1/2)))
'(0.006730890460318273 0.34760666063571943 -0.3953886859214042 0.4921332104978403 0.4416750166258784 0.3838481765334544 -0.06906964265892412 -0.08797936358016623 0.1329820276378333 0.0022764886900572545 -0.34082722987329206 0.4636171831359096 0.15415791540053825 0.179958229286436 -0.27697025509779644 -0.4340068752117059 -0.027190605563960468 0.1504496373919595 -0.4820350062249418 0.10666208951401401)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-real/uniform 10.0 20.0)))
'(15.067308904603182 18.476066606357193 11.046113140785959 19.921332104978404 19.416750166258783 18.838481765334542 14.309303573410759 14.120206364198339 16.329820276378335 15.022764886900573 11.591727701267079 19.636171831359096 16.541579154005383 16.79958229286436 12.230297449022036 10.659931247882941 14.728093944360396 16.504496373919594 10.179649937750582 16.06662089514014)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-real/uniform 0.05 0.05)))
'(0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05)

Note: out-of-order arguments cause an exception!

> (build-list 10 (lambda (i) (random-real/uniform 0.5 -0.5)))
random-real/uniform: contract violation, expected <(and/c
real? (>=/c 0.5))>, given -0.5, which isn't (>=/c 0.5)
  contract from
    /Users/cce/git/planet/fasttest/random.rkt
  blaming program
  contract:
    (->d ((x ...) (y ...)) () (_ ...))
  at: /Users/cce/git/planet/fasttest/random.rkt:137.2

1.3 Textual Data

(random-char) → char?

Produces a random lower-case letter.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-char)))
'(#\n #\w #\c #\z #\y #\w #\l #\k #\q #\n #\e #\z #\r #\r #\f #\b #\m #\q #\a #\p)

(random-string [#:char make-char #:len len]) → string?

make-char : (-> char?) = random-char

len : natural-number/c = (random-natural/poisson 4)

Produces a string of length len with characters generated by make-char.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-string)))
'("kqnezr" "mq" "" "izbf" "joi" "inoj" "uallfu" "xcut" "oa" "qc" "o" "hnyk" "bsxb" "mcyw" "gofkgsd" "fsnuchxj" "ysp" "uhlm" "fo" "rkgjjej")
> (random-seed 1)
> (build-list
   20
   (lambda (i)
     (random-string #:char (lambda () (random-choice #\A #\B))
                    #:len 4)))
'("BBAB" "BBAA" "BBAB" "BBAA" "ABAB" "ABAB" "ABAA" "AABA" "ABAB" "ABBA" "ABBA" "ABAB" "BBAB" "AAAA" "BABA" "AABA" "BBAA" "ABAB" "AABA" "AABB")

(random-symbol [#:string string]) → symbol?

string : string? = (random-string)

Produces an interned symbol with underlying string string.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-symbol)))
'(kqnezr mq || izbf joi inoj uallfu xcut oa qc o hnyk bsxb mcyw gofkgsd fsnuchxj ysp uhlm fo rkgjjej)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-symbol #:string "cat")))
'(cat cat cat cat cat cat cat cat cat cat cat cat cat cat cat cat cat cat cat cat)

(random-keyword [#:string string]) → keyword?

string : string? = (random-string)

Produces an interned keyword with underlying string string.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-keyword)))
'(#:kqnezr #:mq #: #:izbf #:joi #:inoj #:uallfu #:xcut #:oa #:qc #:o #:hnyk #:bsxb #:mcyw #:gofkgsd #:fsnuchxj #:ysp #:uhlm #:fo #:rkgjjej)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-keyword #:string "cat")))
'(#:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat #:cat)

1.4 Lists and S-expressions

(random-list thunk [#:len len]) → list?

thunk : (-> any/c)

len : natural-number/c = (random-natural/poisson 4)

Produces a list of length len of elements generated by thunk.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-list random-string)))
'(("rfbmq" "" "izbf" "joi" "inoj" "uallfu") ("goaqc" "bd" "ihny" "bsxbw") ("vrmyk" "kgs" "zmpnf") ("ysptf" "mcpaf" "hrkgjje" "bxgjyti") () ("gxk" "cttga" "bfjk") ("yxg" "jzw" "jkenzbk" "xyqy" "abwu" "rhk" "ae") ("jfm" "rgg" "w" "mtequxfi" "ncnwz" "pjof") ("sw" "emfy" "qgmk" "mrqgcf" "vr") ("mbm") ("reuwlxtw" "nuk") ("xbtc" "zfp" "yyz" "bvpb" "u" "qoqkgcy") ("si" "llkvg" "glqk" "cry" "atbbedjyy" "q") ("qum" "fhzpvertckml" "bsncig" "ppkh" "jfheftpq" "pz") ("qdpnxht" "i" "ro" "ng" "fwrtrf") ("tao" "llu" "nv" "ek" "xx") ("jotn" "vvblrt" "momlr" "unr" "zrmtnpt") ("t" "zf" "ydnfumc" "zfanoin") ("o" "oymsk" "ro" "yb" "bwqoge") ("" "mbnq" "ji" "csl" "tf" "vumf"))
> (random-seed 1)
> (build-list 20 (lambda (i) (random-list random-string #:len 4)))
'(("kqnezr" "mq" "" "izbf") ("joi" "inoj" "uallfu" "xcut") ("oa" "qc" "o" "hnyk") ("bsxb" "mcyw" "gofkgsd" "fsnuchxj") ("ysp" "uhlm" "fo" "rkgjjej") ("xgjytia" "qnj" "zmg" "ttg") ("rn" "f" "vyyv" "yxgb") ("wqfjjkenz" "pn" "notgab" "rhkpf") ("e" "flgijf" "rggb" "ynzdmt") ("iwur" "cnw" "pjoft" "ppas") ("gemf" "qgmkg" "rqgcfh" "ra") ("gb" "bj" "mreuwlxt" "nukm") ("bzozj" "jcr" "vfay" "bvpbbc") ("qoqkgcyw" "lhcsi" "llkvg" "glqk") ("cry" "atbbedjyy" "q" "snhcqu") ("tcfhzpvertc" "rkebsn" "rn" "pp") ("hvzbjf" "tp" "pzx" "nqlq") ("pnxht" "i" "ro" "ng") ("fwrtrf" "pwbet" "" "lluj") ("n" "ekh" "tiqy" "jotnp"))

(random-atom) → (not/c pair?)

Produces a random boolean, symbol, character, number, or string.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-atom)))
'(#\w () "zrrfbm" #\a #\h -1094 "f" () "ir" () 0.6418003318571719 #\j #f llfuj "xc" 0.6375660828910223 #\a #\c #f ())

(random-sexp	[	#:atom make-atom
		#:improper improper?
		#:size size])	→	any/c

make-atom : (-> (not/c pair?)) = random-atom

improper? : boolean? = #f

size : natural-number/c = (random-natural/poisson 4)

Produces a random cons-tree (if improper?) or nested list (if not) containing size atoms generated by make-atom.

Examples:
> (random-seed 1)
> (build-list 10 (lambda (i) (random-sexp)))
'(((#\r) ((#\a)) #\h) (((#f)) (0.6418003318571719)) (-1897/405+1469/262i xcu (qcg)) ((())) (bsxb (#t)) ("gofkgsd" #\o "snuchx") (-0.33383828860756826 cpaf #\u -463/146+410/137i) ((#f #\u)) (24/17 (#\q)) (cttga -97/404 ()))
> (random-seed 1)
> (build-list 10 (lambda (i) (random-sexp #:atom random-symbol
                                          #:improper #t
                                          #:size 4)))
'((((zrrfbmq . ||) . izbf) jo . qai)  (((uallfu . xcut) . oa) cb . kli)  ((bsxbwh . ywyj) (ofkg . jzmpn) . hxju)  ((|| . iuhlmc) (fhrkgjj . souk) . jy)  ((|| jcgx . hcttg)  bfjk . ktuayxg)  (wqfjjkenz hxyq (bwuo . hkp) . a)   (flgijf (gbdw . mtequxfi) ncnw . pjoft)   ((pas . gemf) (mkgsx . qgcfh) . ra)  (mbm vvxr (kcenukmi . bzoz) . cjc)   (((ayyz . bvpb) . u) qoqkgc . lhcsivi))

1.5 Choices

(random-choice v ...+) → (one-of/c v ...+)

v : any/c

Produces one of its arguments, chosen fairly.

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-choice 1 2 3 4 5 6 7 8 9 10)))
'(6 9 2 10 10 9 5 5 7 6 2 10 7 7 3 1 5 7 1 7)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-choice 'north 'south 'east 'west)))
'(east west north west west west south south east east north west east east north north south east north east)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-choice "single")))
'("single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single" "single")

(random-choice-weighted alist) → (one-of/c (map cdr alist))

alist : (listof (cons/c (>/c 0) any/c))

Produces one of the values (cdr) of alist, weighted by their keys (car).

Examples:
> (random-seed 1)
> (build-list 20 (lambda (i) (random-choice-weighted '((1 . 1) (2 . 2) (3 . 3) (4 . 4)))))
'(3 4 2 4 4 4 3 3 4 3 2 4 4 4 2 1 3 4 1 4)
> (random-seed 1)
> (build-list 20 (lambda (i) (random-choice-weighted '((1 . A) (10 . B)))))
'(B B B B B B B B B B B B B B B A B B A B)

(random-case clause ...+)

clause		=		expr
		\|		expr #:weight weight

Chooses one of the exprs and evaluates it in tail position. Each expression is chosen with the associated weight, default 1.

Examples:
> (random-seed 1)
> (for ([i (in-range 0 20)])
    (random-case (printf "Hello!\n")
                 (printf "Goodbye.\n")))
Goodbye.
Goodbye.
Hello!
Goodbye.
Goodbye.
Goodbye.
Hello!
Hello!
Goodbye.
Goodbye.
Hello!
Goodbye.
Goodbye.
Goodbye.
Hello!
Hello!
Hello!
Goodbye.
Hello!
Goodbye.
(define (random-tree)
  (random-case 'leaf #:weight 2
               (list 'node (random-tree) (random-tree)) #:weight 1))

> (random-seed 1)
> (build-list 20 (lambda (i) (random-tree)))
'(leaf (node leaf (node (node (node leaf leaf) leaf) leaf)) leaf (node leaf (node leaf leaf)) leaf leaf leaf leaf leaf (node leaf leaf) leaf (node leaf leaf) leaf leaf (node leaf leaf) leaf leaf (node leaf (node leaf leaf)) leaf leaf)

1.6 Probabilities

(prob/c) → flat-contract?

(prob/c inc) → flat-contract?

inc : (one-of/c 0 1)

(prob/c zero one) → flat-contract?

zero : 0

one : 1

This contract is intended to accept probability values. It accepts real numbers in the range [0,1], inclusive of zero and/or one if passed as an argument, and exclusive otherwise.

← prev up next →

1.1	Booleans
1.2	Numbers
1.3	Textual Data
1.4	Lists and S-expressions
1.5	Choices
1.6	Probabilities