<NME> variance.js
<BEF> import sumNthPowerDeviations from "./sum_nth_power_deviations.js";

/**
 * The [variance](http://en.wikipedia.org/wiki/Variance)
 * is the sum of squared deviations from the mean.
 *
 * This is an implementation of variance, not sample variance:
 * see the `sampleVariance` method if you want a sample measure.
 * This is an implementation of variance, not sample variance:
 * see the `sampleVariance` method if you want a sample measure.
 *
 * @param {Array<number>} input
 * @returns {number} variance: a value greater than or equal to zero.
 * zero indicates that all values are identical.
 */
function variance(x) {
    // The variance of no numbers is null
    }

    // Find the mean of squared deviations between the
    // mean value and each value.
    return sumNthPowerDeviations(x, 2) / x.length;
}

export default variance;

<MSG> Documentation improvements: adding examples

<DFF> @@ -9,9 +9,11 @@ var mean = require('./mean');
  * This is an implementation of variance, not sample variance:
  * see the `sampleVariance` method if you want a sample measure.
  *
- * @param {Array<number>} input
+ * @param {Array<number>} x a population
  * @returns {number} variance: a value greater than or equal to zero.
  * zero indicates that all values are identical.
+ * @example
+ * ss.variance([1, 2, 3, 4, 5, 6]); //= 2.917
  */
 function variance(x) {
     // The variance of no numbers is null

{'commit': "diff --git a/src/bayesian_classifier.js b/src/bayesian_classifier.js\nindex 7ce8775..6db79aa 100644\n--- a/src/bayesian_classifier.js\n+++ b/src/bayesian_classifier.js\n@@ -5,6 +5,8 @@\n  *\n  * This is a naïve bayesian classifier that takes\n  * singly-nested objects.\n+ *\n+ * @class\n  */\n function BayesianClassifier() {\n     // The number of items that are currently\n@@ -18,8 +20,9 @@ function BayesianClassifier() {\n  * Train the classifier with a new item, which has a single\n  * dimension of Javascript literal keys and values.\n  *\n- * @param {Object} item\n- * @param {string} category\n+ * @param {Object} item an object with singly-deep properties\n+ * @param {string} category the category this item belongs to\n+ * @return {undefined} adds the item to the classifier\n  */\n BayesianClassifier.prototype.train = function(item, category) {\n     // If the data object doesn't have any values\n@@ -52,7 +55,7 @@ BayesianClassifier.prototype.train = function(item, category) {\n  * Generate a score of how well this item matches all\n  * possible categories based on its attributes\n  *\n- * @param {Object} item\n+ * @param {Object} item an item in the same format as with train\n  * @returns {Object} of probabilities that this item belongs to a\n  * given category.\n  */\ndiff --git a/src/harmonic_mean.js b/src/harmonic_mean.js\nindex 6bb9f47..a0387df 100644\n--- a/src/harmonic_mean.js\n+++ b/src/harmonic_mean.js\n@@ -13,6 +13,8 @@\n  *\n  * @param {Array<number>} x input\n  * @returns {number} harmonic mean\n+ * @example\n+ * ss.harmonicMean([2, 3]) //= 2.4\n  */\n function harmonicMean(x) {\n     // The mean of no numbers is null\ndiff --git a/src/linear_regression.js b/src/linear_regression.js\nindex f9aad82..1ab81ef 100644\n--- a/src/linear_regression.js\n+++ b/src/linear_regression.js\n@@ -9,6 +9,8 @@\n  * @param {Array<Array<number>>} data an array of two-element of arrays,\n  * like `[[0, 1], [2, 3]]`\n  * @returns {Object} object containing slope and intersect of regression line\n+ * @example\n+ * linearRegression([[0, 0], [1, 1]]); // { m: 1, b: 0 }\n  */\n function linearRegression(data) {\n \ndiff --git a/src/linear_regression_line.js b/src/linear_regression_line.js\nindex 440a66b..343c67a 100644\n--- a/src/linear_regression_line.js\n+++ b/src/linear_regression_line.js\n@@ -10,6 +10,10 @@\n  * slope and intersect of desired line\n  * @returns {Function} method that computes y-value at any given\n  * x-value on the line.\n+ * @example\n+ * var l = linearRegressionLine(linearRegression([[0, 0], [1, 1]]));\n+ * l(0) //= 0\n+ * l(2) //= 2\n  */\n function linearRegressionLine(mb) {\n     // Return a function that computes a `y` value for each\ndiff --git a/src/mad.js b/src/mad.js\nindex a50650f..720b2d9 100644\n--- a/src/mad.js\n+++ b/src/mad.js\n@@ -9,6 +9,8 @@ var median = require('./median');\n  *\n  * @param {Array<number>} x input array\n  * @returns {number} median absolute deviation\n+ * @example\n+ * mad([1, 1, 2, 2, 4, 6, 9]); //= 1\n  */\n function mad(x) {\n     // The mad of nothing is null\ndiff --git a/src/mixin.js b/src/mixin.js\nindex e4893aa..d50c95b 100644\n--- a/src/mixin.js\n+++ b/src/mixin.js\n@@ -10,6 +10,8 @@\n  * @param {Array} [array=] a single array instance which will be augmented\n  * with the extra methods. If omitted, mixin will apply to all arrays\n  * by changing the global `Array.prototype`.\n+ * @returns {*} the extended Array, or Array.prototype if no object\n+ * is given.\n  *\n  * @example\n  * var myNumbers = [1, 2, 3];\ndiff --git a/src/mode.js b/src/mode.js\nindex f4da1a8..587f4e8 100644\n--- a/src/mode.js\n+++ b/src/mode.js\n@@ -12,6 +12,8 @@\n  *\n  * @param {Array<number>} x input\n  * @returns {number} mode\n+ * @example\n+ * mode([0, 0, 1]); //= 0\n  */\n function mode(x) {\n \ndiff --git a/src/perceptron.js b/src/perceptron.js\nindex 537ed33..d5c8b6b 100644\n--- a/src/perceptron.js\n+++ b/src/perceptron.js\n@@ -4,6 +4,7 @@\n  * This is a single-layer [Perceptron Classifier](http://en.wikipedia.org/wiki/Perceptron) that takes\n  * arrays of numbers and predicts whether they should be classified\n  * as either 0 or 1 (negative or positive examples).\n+ * @class\n  */\n function PerceptronModel() {\n     // The weights, or coefficients of the model;\n@@ -19,7 +20,7 @@ function PerceptronModel() {\n  * **Predict**: Use an array of features with the weight array and bias\n  * to predict whether an example is labeled 0 or 1.\n  *\n- * @param {Array} features\n+ * @param {Array<number>} features an array of features as numbers\n  * @returns {number} 1 if the score is over 0, otherwise 0\n  */\n PerceptronModel.prototype.predict = function(features) {\n@@ -48,7 +49,7 @@ PerceptronModel.prototype.predict = function(features) {\n  * **Train** the classifier with a new example, which is\n  * a numeric array of features and a 0 or 1 label.\n  *\n- * @param {Array} features\n+ * @param {Array<number>} features an array of features as numbers\n  * @param {number} label either 0 or 1\n  * @returns {PerceptronModel} this\n  */\ndiff --git a/src/standard_normal_table.js b/src/standard_normal_table.js\nindex a3b7835..4757f89 100644\n--- a/src/standard_normal_table.js\n+++ b/src/standard_normal_table.js\n@@ -1,19 +1,5 @@\n 'use strict';\n \n-/**\n- * A standard normal table, also called the unit normal table or Z table,\n- * is a mathematical table for the values of Φ (phi), which are the values of\n- * the cumulative distribution function of the normal distribution.\n- * It is used to find the probability that a statistic is observed below,\n- * above, or between values on the standard normal distribution, and by\n- * extension, any normal distribution.\n- *\n- * The probabilities are calculated using formula from\n- * https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_function\n- * The table used is the cumulative, and not cumulative from 0 to mean\n- * (even though the latter has 5 digits precision, instead of 4).\n- */\n-\n var SQRT_2PI = Math.sqrt(2 * Math.PI);\n \n function cumulativeDistribution(z) {\n@@ -28,6 +14,19 @@ function cumulativeDistribution(z) {\n     return Math.round((0.5 + (sum / SQRT_2PI) * Math.exp(-z * z / 2)) * 1e4) / 1e4;\n }\n \n+/**\n+ * A standard normal table, also called the unit normal table or Z table,\n+ * is a mathematical table for the values of Φ (phi), which are the values of\n+ * the cumulative distribution function of the normal distribution.\n+ * It is used to find the probability that a statistic is observed below,\n+ * above, or between values on the standard normal distribution, and by\n+ * extension, any normal distribution.\n+ *\n+ * The probabilities are calculated using the\n+ * [Cumulative distribution function](https://en.wikipedia.org/wiki/Normal_distribution#Cumulative_distribution_function).\n+ * The table used is the cumulative, and not cumulative from 0 to mean\n+ * (even though the latter has 5 digits precision, instead of 4).\n+ */\n var standardNormalTable = [];\n \n for (var z = 0; z <= 3.09; z += 0.01) {\ndiff --git a/src/t_test.js b/src/t_test.js\nindex c901a19..30319c4 100644\n--- a/src/t_test.js\n+++ b/src/t_test.js\n@@ -4,7 +4,7 @@ var standardDeviation = require('./standard_deviation');\n var mean = require('./mean');\n \n /**\n- * This is to compute a one-sample t-test, comparing the mean\n+ * This is to compute [a one-sample t-test](https://en.wikipedia.org/wiki/Student%27s_t-test#One-sample_t-test), comparing the mean\n  * of a sample to a known value, x.\n  *\n  * in this case, we're trying to determine whether the\n@@ -14,7 +14,8 @@ var mean = require('./mean');\n  * a certain level of significance, will let you determine that the\n  * null hypothesis can or cannot be rejected.\n  *\n- * @param {Array<number>} sample\n+ * @param {Array<number>} sample an array of numbers as input\n+ * @param {number} x expected vale of the population mean\n  * @returns {number} value\n  */\n function tTest(sample, x) {\ndiff --git a/src/t_test_two_sample.js b/src/t_test_two_sample.js\nindex 60efc58..84ccac7 100644\n--- a/src/t_test_two_sample.js\n+++ b/src/t_test_two_sample.js\n@@ -22,8 +22,8 @@ var sampleVariance = require('./sample_variance');\n  * a null hypothesis that the two populations that have been sampled into\n  * `sampleX` and `sampleY` are equal to each other.\n  *\n- * @param {Array<number>} sampleX\n- * @param {Array<number>} sampleY\n+ * @param {Array<number>} sampleX a sample as an array of numbers\n+ * @param {Array<number>} sampleY a sample as an array of numbers\n  * @param {number} [difference=0]\n  * @returns {number}\n  */\ndiff --git a/src/variance.js b/src/variance.js\nindex d6b0ea6..e8c88ed 100644\n--- a/src/variance.js\n+++ b/src/variance.js\n@@ -9,9 +9,11 @@ var mean = require('./mean');\n  * This is an implementation of variance, not sample variance:\n  * see the `sampleVariance` method if you want a sample measure.\n  *\n- * @param {Array<number>} input\n+ * @param {Array<number>} x a population\n  * @returns {number} variance: a value greater than or equal to zero.\n  * zero indicates that all values are identical.\n+ * @example\n+ * ss.variance([1, 2, 3, 4, 5, 6]); //= 2.917\n  */\n function variance(x) {\n     // The variance of no numbers is null\n", 'commit_subject': 'Documentation improvements: adding examples', 'repo_name': 'simple-statistics/simple-statistics', 'committer': {'name': 'Tom MacWright', 'email': '96835dd8bfa718bd6447ccc87af89ae1675daeca@macwright.org', 'time_sec': '1437861354', 'tz_offset': '-240', 'date': {'seconds': '1437861354'}}, 'commit_tree': '34f090da8e20053ee8830df2bd131f95721b13c2', 'commit_message': 'Documentation improvements: adding examples\n', 'language_name': 'Shell', 'license': 'isc', 'hunks': "@@ -9,9 +9,11 @@ var mean = require('./mean');\n  * This is an implementation of variance, not sample variance:\n  * see the `sampleVariance` method if you want a sample measure.\n  *\n- * @param {Array<number>} input\n+ * @param {Array<number>} x a population\n  * @returns {number} variance: a value greater than or equal to zero.\n  * zero indicates that all values are identical.\n+ * @example\n+ * ss.variance([1, 2, 3, 4, 5, 6]); //= 2.917\n  */\n function variance(x) {\n     // The variance of no numbers is null\n", 'addition_count': 3, 'deletion_count': 1, 'src_file': 'a/src/variance.js', 'tgt_file': 'b/src/variance.js', 'file_extension': '.js', 'before_file': 'import sumNthPowerDeviations from "./sum_nth_power_deviations.js";\n\n/**\n * The [variance](http://en.wikipedia.org/wiki/Variance)\n * is the sum of squared deviations from the mean.\n *\n * This is an implementation of variance, not sample variance:\n * see the `sampleVariance` method if you want a sample measure.\n * This is an implementation of variance, not sample variance:\n * see the `sampleVariance` method if you want a sample measure.\n *\n * @param {Array<number>} input\n * @returns {number} variance: a value greater than or equal to zero.\n * zero indicates that all values are identical.\n */\nfunction variance(x) {\n    // The variance of no numbers is null\n    }\n\n    // Find the mean of squared deviations between the\n    // mean value and each value.\n    return sumNthPowerDeviations(x, 2) / x.length;\n}\n\nexport default variance;\n', 'message': 'Documentation improvements: adding examples\n', 'author_name': 'Tom MacWright', 'lang': 'js'}