basis/math/statistics/statistics-docs.factor

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