Remove documentation duplication in math.statistics

extra/math/statistics/statistics-docs.factor

@@ -3,13 +3,14 @@ IN: math.statistics
 
 HELP: geometric-mean
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
-{ $description "Computes the geometric mean of all elements in " { $snippet "seq" } ".  The geometric mean measures the central tendency of a data set that minimizes the effects of extreme values." }
+{ $description "Computes the geometric mean of all elements in " { $snippet "seq" } ". The geometric mean measures the central tendency of a data set that minimizes the effects of extreme values." }
 { $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } geometric-mean ." "1.81712059283214" } }
 { $errors "Throws a " { $link signal-error. } " (square-root of 0) if the sequence is empty." } ;
 
 HELP: harmonic-mean
 { $values { "seq" "a sequence of numbers" } { "n" "a non-negative real number"} }
-{ $description "Computes the harmonic mean of the elements in " { $snippet "seq" } ".  The harmonic mean is appropriate when the average of rates is desired." }
+{ $description "Computes the harmonic mean of the elements in " { $snippet "seq" } ". The harmonic mean is appropriate when the average of rates is desired." }
+{ $notes "Positive reals only." }
 { $examples { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } harmonic-mean ." "6/11" } }
 { $errors "Throws a " { $link signal-error. } " (divide by zero) if the sequence is empty." } ;
 
@@ -36,21 +37,21 @@ HELP: range
 
 HELP: std
 { $values { "seq" "a sequence of numbers" } { "x" "a non-negative real number"} }
-{ $description "Computes the standard deviation of " { $snippet "seq" } " by squaring the variance of the sequence.  It measures how widely spread the values in a sequence are about the mean." }
+{ $description "Computes the standard deviation of " { $snippet "seq" } ", which is the square root of the variance. It measures how widely spread the values in a sequence are about the mean." }
 { $examples
   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 } std ." "1.0" }
   { $example "USING: math.statistics prettyprint ;" "{ 1 2 3 4 } std ." "1.290994448735806" } } ;
 
 HELP: ste
   { $values { "seq" "a sequence of numbers" } { "x" "a non-negative real number"} }
-  { $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." }
+  { $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." }
   { $examples
     { $example "USING: math.statistics prettyprint ;" "{ -2 2 } ste ." "2.0" }
     { $example "USING: math.statistics prettyprint ;" "{ -2 2 2 } ste ." "1.333333333333333" } } ;
 
 HELP: var
 { $values { "seq" "a sequence of numbers" } { "x" "a non-negative real number"} }
-{ $description "Computes the variance of " { $snippet "seq" } ".  It's a measurement of the spread of values in a sequence.  The larger the variance, the larger the distance of values from the mean." }
+{ $description "Computes the variance of " { $snippet "seq" } ". It's a measurement of the spread of values in a sequence. The larger the variance, the larger the distance of values from the mean." }
 { $notes "If the number of elements in " { $snippet "seq" } " is 1 or less, it outputs 0." }
 { $examples
   { $example "USING: math.statistics prettyprint ;" "{ 1 } var ." "0" }

extra/math/statistics/statistics.factor

@@ -5,20 +5,15 @@ USING: arrays combinators kernel math math.analysis math.functions sequences
 IN: math.statistics
 
 : mean ( seq -- n )
-    #! arithmetic mean, sum divided by length
     [ sum ] [ length ] bi / ;
 
 : geometric-mean ( seq -- n )
-    #! geometric mean, nth root of product
     [ length ] [ product ] bi nth-root ;
 
 : harmonic-mean ( seq -- n )
-    #! harmonic mean, reciprocal of sum of reciprocals.
-    #! positive reals only
     [ recip ] sigma recip ;
 
 : median ( seq -- n )
-    #! middle number if odd, avg of two middle numbers if even
     natural-sort dup length even? [
         [ midpoint@ dup 1- 2array ] keep nths mean
     ] [
@@ -26,11 +21,10 @@ IN: math.statistics
     ] if ;
 
 : range ( seq -- n )
-    #! max - min
     minmax swap - ;
 
 : var ( seq -- x )
-    #! variance, normalize by N-1
+    #! normalize by N-1
     dup length 1 <= [
         drop 0
     ] [
@@ -39,11 +33,9 @@ IN: math.statistics
     ] if ;
 
 : std ( seq -- x )
-    #! standard deviation, sqrt of variance
     var sqrt ;
 
 : ste ( seq -- x )
-    #! standard error, standard deviation / sqrt ( length of sequence )
     [ std ] [ length ] bi sqrt / ;
 
 : ((r)) ( mean(x) mean(y) {x} {y} -- (r) )