basis/math/statistics/statistics-docs.factor

   1 USING: debugger hashtables help.markup help.syntax kernel math
   2 sequences ;
   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.8171205928321397" } }
   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 ." "1+7/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 { $see-also geometric-mean harmonic-mean } ;
  29
  30 HELP: median
  31 { $values { "seq" sequence } { "x" "a non-negative real number" } }
  32 { $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." }
  33 { $examples
  34   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } median ." "2" }
  35   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } median ." "2+1/2" } }
  36 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
  37
  38 HELP: range
  39 { $values { "seq" sequence } { "x" "a non-negative real number" } }
  40 { $description "Computes the difference of the maximum and minimum values in " { $snippet "seq" } "." }
  41 { $examples
  42   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } range ." "2" }
  43   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } range ." "3" } } ;
  44
  45 HELP: minmax
  46 { $values { "seq" sequence } { "min" real } { "max" real } }
  47 { $description "Finds the minimum and maximum elements of " { $snippet "seq" } " in one pass. Throws an error on an empty sequence." }
  48 { $examples
  49     { $example "USING: arrays math.statistics prettyprint ;"
  50         "{ 1 2 3 } minmax 2array ."
  51         "{ 1 3 }"
  52     }
  53 } ;
  54
  55 HELP: sample-std
  56 { $values { "seq" sequence } { "x" "a non-negative real number" } }
  57 { $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." }
  58 { $examples
  59   { $example "USING: math.statistics prettyprint ;" "{ 7 8 9 } sample-std ." "1.0" } } ;
  60
  61 HELP: sample-ste
  62   { $values { "seq" sequence } { "x" "a non-negative real number" } }
  63   { $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." }
  64   { $examples
  65     { $example "USING: math.statistics prettyprint ;" "{ -2 2 } sample-ste ." "2.0" }
  66   } ;
  67
  68 HELP: sample-var
  69 { $values { "seq" sequence } { "x" "a non-negative real number" } }
  70 { $description "Computes the variance of " { $snippet "seq" } ". It's a measurement of the spread of values in a sequence." }
  71 { $notes "If the number of elements in " { $snippet "seq" } " is 1 or less, it outputs 0." }
  72 { $examples
  73   { $example "USING: math.statistics prettyprint ;" "{ 1 } sample-var ." "0" }
  74   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } sample-var ." "1" }
  75   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } sample-var ." "1+2/3" } } ;
  76
  77 HELP: population-cov
  78 { $values { "x-seq" sequence } { "y-seq" sequence } { "cov" "a real number" } }
  79 { $description "Computes the covariance of two sequences, " { $snippet "x-seq" } " and " { $snippet "y-seq" } "." } ;
  80
  81 HELP: population-corr
  82 { $values { "x-seq" sequence } { "y-seq" sequence } { "corr" "a real number" } }
  83 { $description "Computes the correlation of two sequences, " { $snippet "x-seq" } " and " { $snippet "y-seq" } "." } ;
  84
  85 HELP: spearman-corr
  86 { $values { "x-seq" sequence } { "y-seq" sequence } { "corr" "a real number" } }
  87 { $description "Computes the Spearman's correlation of two sequences, " { $snippet "x-seq" } " and " { $snippet "y-seq" } "." $nl "For more information see " { $url "https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient" } "." } ;
  88
  89 HELP: histogram
  90 { $values
  91     { "seq" sequence }
  92     { "hashtable" hashtable }
  93 }
  94 { $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." }
  95 { $examples
  96     { $example "! Count the number of times an element appears in a sequence."
  97                "USING: prettyprint math.statistics ;"
  98                "\"aaabc\" histogram ."
  99                "H{ { 97 3 } { 98 1 } { 99 1 } }"
 100     }
 101 } ;
 102
 103
 104 HELP: histogram-by
 105 { $values
 106     { "seq" sequence }
 107     { "quot" { $quotation ( x -- bin ) } }
 108     { "hashtable" hashtable }
 109 }
 110 { $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." }
 111 { $examples
 112     { $unchecked-example "! Count the number of times letters and non-letters appear in a sequence."
 113                "USING: prettyprint math.statistics unicode ;"
 114                "\"aaa123bc\" [ letter? ] histogram-by ."
 115                "H{ { t 5 } { f 3 } }"
 116     }
 117 } ;
 118
 119 HELP: histogram!
 120 { $values
 121     { "hashtable" hashtable } { "seq" sequence }
 122 }
 123 { $description "Takes an existing hashtable and uses " { $link histogram } " to continue counting the number of occurrences of each element." }
 124 { $examples
 125     { $example "! Count the number of times the elements of two sequences appear."
 126                "USING: prettyprint math.statistics ;"
 127                "\"aaabc\" histogram \"aaaaaabc\" histogram! ."
 128                "H{ { 97 9 } { 98 2 } { 99 2 } }"
 129     }
 130 } ;
 131
 132 HELP: sorted-histogram
 133 { $values
 134     { "seq" sequence }
 135     { "alist" "an array of key/value pairs" }
 136 }
 137 { $description "Outputs a " { $link histogram } " of a sequence sorted by number of occurrences from lowest to highest." }
 138 { $examples
 139     { $example "USING: prettyprint math.statistics ;"
 140         "\"abababbbbbbc\" sorted-histogram ."
 141         "{ { 99 1 } { 97 3 } { 98 8 } }"
 142     }
 143 } ;
 144
 145 HELP: cum-sum
 146 { $values { "seq" sequence } { "seq'" sequence } }
 147 { $description "Returns the cumulative sum of " { $snippet "seq" } "." }
 148 { $examples
 149     { $example "USING: math.statistics prettyprint ;"
 150                "{ 1 -1 2 -1 4 } cum-sum ."
 151                "{ 1 0 2 1 5 }"
 152     }
 153 } ;
 154
 155 HELP: cum-sum0
 156 { $values { "seq" sequence } { "seq'" sequence } }
 157 { $description "Returns the cumulative sum of " { $snippet "seq" } " starting with 0 and not including the whole sum." }
 158 { $examples
 159     { $example "USING: math.statistics prettyprint ;"
 160                "{ 1 -1 2 -1 4 } cum-sum0 ."
 161                "{ 0 1 0 2 1 }"
 162     }
 163 } ;
 164
 165 HELP: cum-count
 166 { $values { "seq" sequence } { "quot" { $quotation ( elt -- ? ) } } { "seq'" sequence } }
 167 { $description "Returns the cumulative count of how many times " { $snippet "quot" } " returns true." }
 168 { $examples
 169     { $example "USING: math math.statistics prettyprint ;"
 170                "{ 1 -1 2 -1 4 } [ 0 < ] cum-count ."
 171                "{ 0 1 1 2 2 }"
 172     }
 173 } ;
 174
 175
 176 HELP: cum-product
 177 { $values { "seq" sequence } { "seq'" sequence } }
 178 { $description "Returns the cumulative product of " { $snippet "seq" } "." }
 179 { $examples
 180     { $example "USING: math.statistics prettyprint ;"
 181                "{ 2 3 4 } cum-product ."
 182                "{ 2 6 24 }"
 183     }
 184 } ;
 185
 186 HELP: cum-product1
 187 { $values { "seq" sequence } { "seq'" sequence } }
 188 { $description "Returns the cumulative product of " { $snippet "seq" } " starting with 1 and not including the whole product." }
 189 { $examples
 190     { $example "USING: math.statistics prettyprint ;"
 191                "{ 2 3 4 } cum-product1 ."
 192                "{ 1 2 6 }"
 193     }
 194 } ;
 195
 196 HELP: cum-mean
 197 { $values { "seq" sequence } { "seq'" sequence } }
 198 { $description "Returns the cumulative mean of " { $snippet "seq" } "." }
 199 { $examples
 200     { $example "USING: math.statistics prettyprint ;"
 201                "{ 1.0 2.0 3.0 } cum-mean ."
 202                "{ 1.0 1.5 2.0 }"
 203     }
 204 } ;
 205
 206 HELP: cum-min
 207 { $values { "seq" sequence } { "seq'" sequence } }
 208 { $description "Returns the cumulative min of " { $snippet "seq" } "." }
 209 { $examples
 210     { $example "USING: math.statistics prettyprint ;"
 211                "{ 5 3 4 1 } cum-min ."
 212                "{ 5 3 3 1 }"
 213     }
 214 } ;
 215
 216 HELP: cum-max
 217 { $values { "seq" sequence } { "seq'" sequence } }
 218 { $description "Returns the cumulative max of " { $snippet "seq" } "." }
 219 { $examples
 220     { $example "USING: math.statistics prettyprint ;"
 221                "{ 1 -1 3 5 } cum-max ."
 222                "{ 1 1 3 5 }"
 223     }
 224 } ;
 225
 226 HELP: standardize
 227 { $values { "u" sequence } { "v" sequence } }
 228 { $description "Shifts and rescales the elements of " { $snippet "u" } " to have zero mean and unit sample variance." } ;
 229
 230 HELP: differences
 231 { $values { "u" sequence } { "v" sequence } }
 232 { $description "Returns the successive differences of elements in " { $snippet "u" } "." } ;
 233
 234 HELP: rescale
 235 { $values { "u" sequence } { "v" sequence } }
 236 { $description "Returns " { $snippet "u" } " rescaled to run from 0 to 1 over the range min to max." } ;
 237
 238 HELP: z-score
 239 { $values { "seq" sequence } { "n" number } }
 240 { $description "Calculates the Z-Score for " { $snippet "seq" } "." } ;
 241
 242 HELP: dcg
 243 { $values
 244     { "scores" sequence }
 245     { "dcg" number }
 246 }
 247 { $description "Calculates the discounted cumulative gain from a list of scores. The discounted cumulative gain can be used to compare two lists of results against each other given scores for each of the results."
 248 $nl
 249 " See " { $url "https://en.wikipedia.org/wiki/Discounted_cumulative_gain" }
 250 } ;
 251
 252 HELP: ndcg
 253 { $values
 254     { "scores" sequence }
 255     { "ndcg" number }
 256 }
 257 { $description "Calculates the normalized discounted cumulative gain from a list of scores. The ndcg is the discounted cumulative gain divided by the theoretical maximum dcg for the given list."
 258 $nl
 259 "See " { $url "https://en.wikipedia.org/wiki/Discounted_cumulative_gain" }
 260 } ;
 261
 262 { dcg ndcg } related-words
 263
 264 ARTICLE: "histogram" "Computing histograms"
 265 "Counting elements in a sequence:"
 266 { $subsections
 267     histogram
 268     histogram-by
 269     histogram!
 270     sorted-histogram
 271 } ;
 272
 273 ARTICLE: "cumulative" "Computing cumulative sequences"
 274 "Cumulative words build on " { $link accumulate } " and " { $link accumulate* } "."
 275 $nl
 276 "Cumulative math:"
 277 { $subsections
 278     cum-sum
 279     cum-sum0
 280     cum-product
 281     cum-product1
 282 }
 283 "Cumulative comparisons:"
 284 { $subsections
 285     cum-min
 286     cum-max
 287 }
 288 "Cumulative counting:"
 289 { $subsections
 290     cum-count
 291 } ;
 292
 293 ARTICLE: "math.statistics" "Statistics"
 294 "Computing the mean:"
 295 { $subsections mean geometric-mean harmonic-mean }
 296 "Computing the median:"
 297 { $subsections median lower-median upper-median medians }
 298 "Computing the mode:"
 299 { $subsections mode }
 300 "Computing the population standard deviation, standard error, and variance:"
 301 { $subsections population-std population-ste population-var }
 302 "Computing the sample standard deviation, standard error, and variance:"
 303 { $subsections sample-std sample-ste sample-var }
 304 "Computing the nth delta-degrees-of-freedom statistics:"
 305 { $subsections std-ddof ste-ddof var-ddof }
 306 "Computing the range and minimum and maximum elements:"
 307 { $subsections range minmax }
 308 "Computing the kth smallest element:"
 309 { $subsections kth-smallest }
 310 "Counting the frequency of occurrence of elements:"
 311 { $subsections "histogram" }
 312 "Computing cumulative sequences:"
 313 { $subsections "cumulative" }
 314 "Calculating discounted cumulative gain:"
 315 { $subsections dcg ndcg } ;
 316
 317 ABOUT: "math.statistics"
 318
 319 { var-ddof population-var sample-var } related-words
 320 { std-ddof population-std sample-std } related-words
 321 { ste-ddof population-ste sample-ste } related-words
 322 { corr-ddof population-corr sample-corr } related-words
 323 { cov-ddof population-cov sample-cov } related-words
 324
 325 { sum-of-squares sum-of-cubes sum-of-quads } related-words