basis/math/statistics/statistics-docs.factor

   1 USING: assocs debugger hashtables help.markup help.syntax
   2 quotations sequences math ;
   3 IN: math.statistics
   4
   5 HELP: geometric-mean
   6 { $values { "seq" sequence } { "x" "a non-negative real number"} }
   7 { $description "Computes the geometric mean of all elements in " { $snippet "seq" } ". The geometric mean measures the central tendency of a data set and minimizes the effects of extreme values." }
   8 { $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } geometric-mean ." "1.81712059283214" } }
   9 { $errors "Throws a " { $link signal-error. } " (square-root of 0) if the sequence is empty." } ;
  10
  11 HELP: harmonic-mean
  12 { $values { "seq" sequence } { "x" "a non-negative real number"} }
  13 { $description "Computes the harmonic mean of the elements in " { $snippet "seq" } ". The harmonic mean is appropriate when the average of rates is desired." }
  14 { $notes "Positive reals only." }
  15 { $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } harmonic-mean ." "6/11" } }
  16 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
  17
  18 HELP: mean
  19 { $values { "seq" sequence } { "x" "a non-negative real number"} }
  20 { $description "Computes the arithmetic mean of the elements in " { $snippet "seq" } "." }
  21 { $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } mean ." "2" } }
  22 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
  23
  24 HELP: median
  25 { $values { "seq" sequence } { "x" "a non-negative real number"} }
  26 { $description "Computes the median of " { $snippet "seq" } " by finding the middle element of the sequence using " { $link kth-smallest } ". If there is an even number of elements in the sequence, the median is not unique, so the mean of the two middle values is output." }
  27 { $examples
  28   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } median ." "2" }
  29   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } median ." "2+1/2" } }
  30 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
  31
  32 HELP: range
  33 { $values { "seq" sequence } { "x" "a non-negative real number"} }
  34 { $description "Computes the difference of the maximum and minimum values in " { $snippet "seq" } "." }
  35 { $examples
  36   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } range ." "2" }
  37   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } range ." "3" } } ;
  38
  39 HELP: minmax
  40 { $values { "seq" sequence } { "min" real } { "max" real } }
  41 { $description "Finds the minimum and maximum elements of " { $snippet "seq" } " in one pass. Throws an error on an empty sequence." }
  42 { $examples
  43     { $example "USING: arrays math.statistics prettyprint ;"
  44         "{ 1 2 3 } minmax 2array ."
  45         "{ 1 3 }"
  46     }
  47 } ;
  48
  49 HELP: sample-std
  50 { $values { "seq" sequence } { "x" "a non-negative real number"} }
  51 { $description "Computes the sample standard deviation of " { $snippet "seq" } ", which is the square root of the sample variance. It measures how widely spread the values in a sequence are about the mean for a random subset of a dataset." }
  52 { $examples
  53   { $example "USING: math.statistics prettyprint ;" "{ 7 8 9 } sample-std ." "1.0" } } ;
  54
  55 HELP: sample-ste
  56   { $values { "seq" sequence } { "x" "a non-negative real number"} }
  57   { $description "Computes the standard error of the mean for " { $snippet "seq" } ". It's defined as the standard deviation divided by the square root of the length of the sequence, and measures uncertainty associated with the estimate of the mean." }
  58   { $examples
  59     { $example "USING: math.statistics prettyprint ;" "{ -2 2 } sample-ste ." "2.0" }
  60   } ;
  61
  62 HELP: sample-var
  63 { $values { "seq" sequence } { "x" "a non-negative real number"} }
  64 { $description "Computes the variance of " { $snippet "seq" } ". It's a measurement of the spread of values in a sequence." }
  65 { $notes "If the number of elements in " { $snippet "seq" } " is 1 or less, it outputs 0." }
  66 { $examples
  67   { $example "USING: math.statistics prettyprint ;" "{ 1 } sample-var ." "0" }
  68   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } sample-var ." "1" }
  69   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } sample-var ." "1+2/3" } } ;
  70
  71 HELP: population-cov
  72 { $values { "{x}" sequence } { "{y}" sequence } { "cov" "a real number" } }
  73 { $description "Computes the covariance of two sequences, " { $snippet "{x}" } " and " { $snippet "{y}" } "." } ;
  74
  75 HELP: population-corr
  76 { $values { "{x}" sequence } { "{y}" sequence } { "corr" "a real number" } }
  77 { $description "Computes the correlation of two sequences, " { $snippet "{x}" } " and " { $snippet "{y}" } "." } ;
  78
  79 HELP: histogram
  80 { $values
  81     { "seq" sequence }
  82     { "hashtable" hashtable }
  83 }
  84 { $description "Returns a hashtable where the keys are the elements of the sequence and the values are the number of times they appeared in that sequence." }
  85 { $examples
  86     { $example "! Count the number of times an element appears in a sequence."
  87                "USING: prettyprint math.statistics ;"
  88                "\"aaabc\" histogram ."
  89                "H{ { 97 3 } { 98 1 } { 99 1 } }"
  90     }
  91 } ;
  92
  93
  94 HELP: histogram-by
  95 { $values
  96     { "seq" sequence }
  97     { "quot" { $quotation "( x -- bin )" } }
  98     { "hashtable" hashtable }
  99 }
 100 { $description "Returns a hashtable where the keys are the elements of the sequence binned by being passed through " { $snippet "quot" } ", and the values are the number of times members of each bin appeared in that sequence." }
 101 { $examples
 102     { $unchecked-example "! Count the number of times letters and non-letters appear in a sequence."
 103                "USING: prettyprint math.statistics unicode.categories ;"
 104                "\"aaa123bc\" [ letter? ] histogram-by ."
 105                "H{ { t 5 } { f 3 } }"
 106     }
 107 } ;
 108
 109 HELP: histogram!
 110 { $values
 111     { "hashtable" hashtable } { "seq" sequence }
 112 }
 113 { $description "Takes an existing hashtable and uses " { $link histogram } " to continue counting the number of occurrences of each element." }
 114 { $examples
 115     { $example "! Count the number of times the elements of two sequences appear."
 116                "USING: prettyprint math.statistics ;"
 117                "\"aaabc\" histogram \"aaaaaabc\" histogram! ."
 118                "H{ { 97 9 } { 98 2 } { 99 2 } }"
 119     }
 120 } ;
 121
 122 HELP: sorted-histogram
 123 { $values
 124     { "seq" sequence }
 125     { "alist" "an array of key/value pairs" }
 126 }
 127 { $description "Outputs a " { $link histogram } " of a sequence sorted by number of occurrences from lowest to highest." }
 128 { $examples
 129     { $example "USING: prettyprint math.statistics ;"
 130         """"abababbbbbbc" sorted-histogram ."""
 131         "{ { 99 1 } { 97 3 } { 98 8 } }"
 132     }
 133 } ;
 134
 135 HELP: sequence>assoc
 136 { $values
 137     { "seq" sequence } { "map-quot" $quotation } { "insert-quot" quotation } { "exemplar" "an exemplar assoc" }
 138     { "assoc" assoc }
 139 }
 140 { $description "Iterates over a sequence, allowing elements of the sequence to be added to a newly created " { $snippet "assoc" } ". The " { $snippet "map-quot" } " gets passed each element from the sequence. Its outputs are passed along with the assoc being constructed to the " { $snippet "insert-quot" } ", which can modify the assoc in response." }
 141 { $examples
 142     { $example "! Iterate over a sequence and increment the count at each element"
 143                "! The first quotation has stack effect ( key -- key ), a no-op"
 144                "USING: assocs prettyprint kernel math.statistics ;"
 145                "\"aaabc\" [ ] [ inc-at ] H{ } sequence>assoc ."
 146                "H{ { 97 3 } { 98 1 } { 99 1 } }"
 147     }
 148 } ;
 149
 150 HELP: sequence>assoc!
 151 { $values
 152     { "assoc" assoc } { "seq" sequence } { "map-quot" quotation } { "insert-quot" quotation } }
 153 { $description "Iterates over a sequence, allowing elements of the sequence to be added to an existing " { $snippet "assoc" } ". The " { $snippet "map-quot" } " gets passed each element from the sequence. Its outputs are passed along with the assoc being constructed to the " { $snippet "insert-quot" } ", which can modify the assoc in response." }
 154 { $examples
 155     { $example "! Iterate over a sequence and add the counts to an existing assoc"
 156                "USING: assocs prettyprint math.statistics kernel ;"
 157                "H{ { 97 2 } { 98 1 } } clone \"aaabc\" [ ] [ inc-at ] sequence>assoc! ."
 158                "H{ { 97 5 } { 98 2 } { 99 1 } }"
 159     }
 160 } ;
 161
 162 HELP: sequence>hashtable
 163 { $values
 164     { "seq" sequence } { "map-quot" quotation } { "insert-quot" quotation }
 165     { "hashtable" hashtable }
 166 }
 167 { $description "Iterates over a sequence, allowing elements of the sequence to be added to a newly created hashtable. The " { $snippet "map-quot" } " gets passed each element from the sequence. Its outputs are passed along with the assoc being constructed to the " { $snippet "insert-quot" } ", which can modify the assoc in response." }
 168 { $examples
 169     { $example "! Count the number of times an element occurs in a sequence"
 170                "USING: assocs kernel prettyprint math.statistics ;"
 171                "\"aaabc\" [ ] [ inc-at ] sequence>hashtable ."
 172                "H{ { 97 3 } { 98 1 } { 99 1 } }"
 173     }
 174 } ;
 175
 176 HELP: cum-sum
 177 { $values { "seq" sequence } { "seq'" sequence } }
 178 { $description "Returns the cumulative sum of " { $snippet "seq" } "." }
 179 { $examples
 180     { $example "USING: math.statistics prettyprint ;"
 181                "{ 1 -1 2 -1 4 } cum-sum ."
 182                "{ 1 0 2 1 5 }"
 183     }
 184 } ;
 185
 186 HELP: cum-count
 187 { $values { "seq" sequence } { "quot" quotation } { "seq'" sequence } }
 188 { $description "Returns the cumulative count of how many times " { $snippet "quot" } " returns true." }
 189 { $examples
 190     { $example "USING: math math.statistics prettyprint ;"
 191                "{ 1 -1 2 -1 4 } [ 0 < ] cum-count ."
 192                "{ 0 1 1 2 2 }"
 193     }
 194 } ;
 195
 196
 197 HELP: cum-product
 198 { $values { "seq" sequence } { "seq'" sequence } }
 199 { $description "Returns the cumulative product of " { $snippet "seq" } "." }
 200 { $examples
 201     { $example "USING: math.statistics prettyprint ;"
 202                "{ 1 2 3 4 } cum-product ."
 203                "{ 1 2 6 24 }"
 204     }
 205 } ;
 206
 207 HELP: cum-mean
 208 { $values { "seq" sequence } { "seq'" sequence } }
 209 { $description "Returns the cumulative mean of " { $snippet "seq" } "." }
 210 { $examples
 211     { $example "USING: math.statistics prettyprint ;"
 212                "{ 1.0 2.0 3.0 } cum-mean ."
 213                "{ 1.0 1.5 2.0 }"
 214     }
 215 } ;
 216
 217 HELP: cum-min
 218 { $values { "seq" sequence } { "seq'" sequence } }
 219 { $description "Returns the cumulative min of " { $snippet "seq" } "." }
 220 { $examples
 221     { $example "USING: math.statistics prettyprint ;"
 222                "{ 5 3 4 1 } cum-min ."
 223                "{ 5 3 3 1 }"
 224     }
 225 } ;
 226
 227 HELP: cum-max
 228 { $values { "seq" sequence } { "seq'" sequence } }
 229 { $description "Returns the cumulative max of " { $snippet "seq" } "." }
 230 { $examples
 231     { $example "USING: math.statistics prettyprint ;"
 232                "{ 1 -1 3 5 } cum-max ."
 233                "{ 1 1 3 5 }"
 234     }
 235 } ;
 236
 237 HELP: standardize
 238 { $values { "u" sequence } { "v" sequence } }
 239 { $description "Shifts and rescales the elements of " { $snippet "u" } " to have zero mean and unit sample variance." } ;
 240
 241 HELP: differences
 242 { $values { "u" sequence } { "v" sequence } }
 243 { $description "Returns the successive differences of elements in " { $snippet "u" } "." } ;
 244
 245 HELP: rescale
 246 { $values { "u" sequence } { "v" sequence } }
 247 { $description "Returns " { $snippet "u" } " rescaled to run from 0 to 1 over the range min to max." } ;
 248
 249 HELP: collect-by
 250 { $values
 251     { "seq" sequence } { "quot" { $quotation "( ... obj -- ... key )" } }
 252     { "hashtable" hashtable }
 253 }
 254 { $description "Applies a quotation to each element in the input sequence and returns a " { $snippet "hashtable" } " of like elements. The keys of this " { $snippet "hashtable" } " are the output of " { $snippet "quot" } " and the values at each key are the elements that transformed to that key." }
 255 { $examples
 256     "Collect even and odd elements:"
 257     { $example
 258                "USING: math math.statistics prettyprint ;"
 259                "{ 11 12 13 14 14 13 12 11 } [ odd? ] collect-by ."
 260                "H{ { f V{ 12 14 14 12 } } { t V{ 11 13 13 11 } } }"
 261     }
 262 }
 263 { $notes "May be named " { $snippet "group-by" } " in other languages." } ;
 264
 265 HELP: collect-index-by
 266 { $values
 267     { "seq" sequence } { "quot" { $quotation "( ... obj -- ... key )" } }
 268     { "hashtable" hashtable }
 269 }
 270 { $description "Applies a quotation to each element in the input sequence and returns a " { $snippet "hashtable" } " of like elements. The keys of this " { $snippet "hashtable" } " are the output of " { $snippet "quot" } " and the values at each key are the indices for the elements that transformed to that key." }
 271 { $examples
 272     "Collect even and odd elements:"
 273     { $example
 274                "USING: math math.statistics prettyprint ;"
 275                "{ 11 12 13 14 14 13 12 11 } [ odd? ] collect-index-by ."
 276                "H{ { f V{ 1 3 4 6 } } { t V{ 0 2 5 7 } } }"
 277     }
 278 } ;
 279
 280 HELP: z-score
 281 { $values { "seq" sequence } { "n" number } }
 282 { $description "Calculates the Z-Score for " { $snippet "seq" } "." } ;
 283
 284 ARTICLE: "histogram" "Computing histograms"
 285 "Counting elements in a sequence:"
 286 { $subsections
 287     histogram
 288     histogram-by
 289     histogram!
 290     sorted-histogram
 291 }
 292 "Combinators for implementing histogram:"
 293 { $subsections
 294     sequence>assoc
 295     sequence>assoc!
 296     sequence>hashtable
 297 } ;
 298
 299 ARTICLE: "cumulative" "Computing cumulative sequences"
 300 "Cumulative mapping combinators:"
 301 { $subsections
 302     cum-map
 303 }
 304 "Cumulative math:"
 305 { $subsections
 306     cum-sum
 307     cum-sum0
 308     cum-product
 309 }
 310 "Cumulative comparisons:"
 311 { $subsections
 312     cum-min
 313     cum-max
 314 }
 315 "Cumulative counting:"
 316 { $subsections
 317     cum-count
 318 } ;
 319
 320 ARTICLE: "math.statistics" "Statistics"
 321 "Computing the mean:"
 322 { $subsections mean geometric-mean harmonic-mean }
 323 "Computing the median:"
 324 { $subsections median lower-median upper-median medians }
 325 "Computing the mode:"
 326 { $subsections mode }
 327 "Computing the population standard deviation, standard error, and variance:"
 328 { $subsections population-std population-ste population-var }
 329 "Computing the sample standard deviation, standard error, and variance:"
 330 { $subsections sample-std sample-ste sample-var }
 331 "Computing the nth delta-degrees-of-freedom statistics:"
 332 { $subsections std-ddof ste-ddof var-ddof }
 333 "Computing the range and minimum and maximum elements:"
 334 { $subsections range minmax }
 335 "Computing the kth smallest element:"
 336 { $subsections kth-smallest }
 337 "Counting the frequency of occurrence of elements:"
 338 { $subsections "histogram" }
 339 "Collecting related items:"
 340 { $subsections collect-by collect-index-by }
 341 "Computing cumulative sequences:"
 342 { $subsections "cumulative" } ;
 343
 344 ABOUT: "math.statistics"
 345
 346 { var-ddof population-var sample-var } related-words
 347 { std-ddof population-std sample-std } related-words
 348 { ste-ddof population-ste sample-ste } related-words
 349 { corr-ddof population-corr sample-corr } related-words
 350 { cov-ddof population-cov sample-cov } related-words