]> gitweb.factorcode.org Git - factor.git/blob - basis/math/statistics/statistics-docs.factor
5c3ed0653b0dc114f9bef8879fe1b647a7086e47
[factor.git] / 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.categories ;"
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-count
192 { $values { "seq" sequence } { "quot" quotation } { "seq'" sequence } }
193 { $description "Returns the cumulative count of how many times " { $snippet "quot" } " returns true." }
194 { $examples
195     { $example "USING: math math.statistics prettyprint ;"
196                "{ 1 -1 2 -1 4 } [ 0 < ] cum-count ."
197                "{ 0 1 1 2 2 }"
198     }
199 } ;
200
201
202 HELP: cum-product
203 { $values { "seq" sequence } { "seq'" sequence } }
204 { $description "Returns the cumulative product of " { $snippet "seq" } "." }
205 { $examples
206     { $example "USING: math.statistics prettyprint ;"
207                "{ 1 2 3 4 } cum-product ."
208                "{ 1 2 6 24 }"
209     }
210 } ;
211
212 HELP: cum-mean
213 { $values { "seq" sequence } { "seq'" sequence } }
214 { $description "Returns the cumulative mean of " { $snippet "seq" } "." }
215 { $examples
216     { $example "USING: math.statistics prettyprint ;"
217                "{ 1.0 2.0 3.0 } cum-mean ."
218                "{ 1.0 1.5 2.0 }"
219     }
220 } ;
221
222 HELP: cum-min
223 { $values { "seq" sequence } { "seq'" sequence } }
224 { $description "Returns the cumulative min of " { $snippet "seq" } "." }
225 { $examples
226     { $example "USING: math.statistics prettyprint ;"
227                "{ 5 3 4 1 } cum-min ."
228                "{ 5 3 3 1 }"
229     }
230 } ;
231
232 HELP: cum-max
233 { $values { "seq" sequence } { "seq'" sequence } }
234 { $description "Returns the cumulative max of " { $snippet "seq" } "." }
235 { $examples
236     { $example "USING: math.statistics prettyprint ;"
237                "{ 1 -1 3 5 } cum-max ."
238                "{ 1 1 3 5 }"
239     }
240 } ;
241
242 HELP: standardize
243 { $values { "u" sequence } { "v" sequence } }
244 { $description "Shifts and rescales the elements of " { $snippet "u" } " to have zero mean and unit sample variance." } ;
245
246 HELP: differences
247 { $values { "u" sequence } { "v" sequence } }
248 { $description "Returns the successive differences of elements in " { $snippet "u" } "." } ;
249
250 HELP: rescale
251 { $values { "u" sequence } { "v" sequence } }
252 { $description "Returns " { $snippet "u" } " rescaled to run from 0 to 1 over the range min to max." } ;
253
254 HELP: collect-by
255 { $values
256     { "seq" sequence } { "quot" { $quotation ( ... obj -- ... key ) } }
257     { "hashtable" hashtable }
258 }
259 { $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." }
260 { $examples
261     "Collect even and odd elements:"
262     { $example
263                "USING: math math.statistics prettyprint ;"
264                "{ 11 12 13 14 14 13 12 11 } [ odd? ] collect-by ."
265                "H{ { t V{ 11 13 13 11 } } { f V{ 12 14 14 12 } } }"
266     }
267 }
268 { $notes "May be named " { $snippet "group-by" } " in other languages." } ;
269
270 HELP: collect-index-by
271 { $values
272     { "seq" sequence } { "quot" { $quotation ( ... obj -- ... key ) } }
273     { "hashtable" hashtable }
274 }
275 { $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." }
276 { $examples
277     "Collect even and odd elements:"
278     { $example
279                "USING: math math.statistics prettyprint ;"
280                "{ 11 12 13 14 14 13 12 11 } [ odd? ] collect-index-by ."
281                "H{ { t V{ 0 2 5 7 } } { f V{ 1 3 4 6 } } }"
282     }
283 } ;
284
285 HELP: z-score
286 { $values { "seq" sequence } { "n" number } }
287 { $description "Calculates the Z-Score for " { $snippet "seq" } "." } ;
288
289 ARTICLE: "histogram" "Computing histograms"
290 "Counting elements in a sequence:"
291 { $subsections
292     histogram
293     histogram-by
294     histogram!
295     sorted-histogram
296 }
297 "Combinators for implementing histogram:"
298 { $subsections
299     sequence>assoc
300     sequence>assoc!
301     sequence>hashtable
302 } ;
303
304 ARTICLE: "cumulative" "Computing cumulative sequences"
305 "Cumulative mapping combinators:"
306 { $subsections
307     cum-map
308 }
309 "Cumulative math:"
310 { $subsections
311     cum-sum
312     cum-sum0
313     cum-product
314 }
315 "Cumulative comparisons:"
316 { $subsections
317     cum-min
318     cum-max
319 }
320 "Cumulative counting:"
321 { $subsections
322     cum-count
323 } ;
324
325 ARTICLE: "math.statistics" "Statistics"
326 "Computing the mean:"
327 { $subsections mean geometric-mean harmonic-mean }
328 "Computing the median:"
329 { $subsections median lower-median upper-median medians }
330 "Computing the mode:"
331 { $subsections mode }
332 "Computing the population standard deviation, standard error, and variance:"
333 { $subsections population-std population-ste population-var }
334 "Computing the sample standard deviation, standard error, and variance:"
335 { $subsections sample-std sample-ste sample-var }
336 "Computing the nth delta-degrees-of-freedom statistics:"
337 { $subsections std-ddof ste-ddof var-ddof }
338 "Computing the range and minimum and maximum elements:"
339 { $subsections range minmax }
340 "Computing the kth smallest element:"
341 { $subsections kth-smallest }
342 "Counting the frequency of occurrence of elements:"
343 { $subsections "histogram" }
344 "Collecting related items:"
345 { $subsections collect-by collect-index-by }
346 "Computing cumulative sequences:"
347 { $subsections "cumulative" } ;
348
349 ABOUT: "math.statistics"
350
351 { var-ddof population-var sample-var } related-words
352 { std-ddof population-std sample-std } related-words
353 { ste-ddof population-ste sample-ste } related-words
354 { corr-ddof population-corr sample-corr } related-words
355 { cov-ddof population-cov sample-cov } related-words