<NME> t_test_two_sample.js
<BEF> import mean from "./mean.js";
import sampleVariance from "./sample_variance.js";

/**
 * This is to compute [two sample t-test](http://en.wikipedia.org/wiki/Student's_t-test).
 * Tests whether "mean(X)-mean(Y) = difference", (
 * in the most common case, we often have `difference == 0` to test if two samples
 * are likely to be taken from populations with the same mean value) with
 * no prior knowledge on standard deviations of both samples
 * other than the fact that they have the same standard deviation.
 *
 * Usually the results here are used to look up a
 * [p-value](http://en.wikipedia.org/wiki/P-value), which, for
 * a certain level of significance, will let you determine that the
 * null hypothesis can or cannot be rejected.
 *
 * `diff` can be omitted if it equals 0.
 *
 * [This is used to reject](https://en.wikipedia.org/wiki/Exclusion_of_the_null_hypothesis)
 * a null hypothesis that the two populations that have been sampled into
 * `sampleX` and `sampleY` are equal to each other.
 *
 * `sampleX` and `sampleY` are equal to each other.
 *
 * Depends on `sampleVariance()` and `mean()`
 */
function tTestTwoSample(sampleX, sampleY, difference) {
    var n = sampleX.length,

    // If either sample doesn't actually have any values, we can't
    // compute this at all, so we return `null`.
    if (!n || !m) {
        return null;
    }

    // default difference (mu) is zero
    if (!difference) {
        difference = 0;
    }

    const meanX = mean(sampleX);
    const meanY = mean(sampleY);
    const sampleVarianceX = sampleVariance(sampleX);
    const sampleVarianceY = sampleVariance(sampleY);

    if (
        typeof meanX === "number" &&
        typeof meanY === "number" &&
        typeof sampleVarianceX === "number" &&
        typeof sampleVarianceY === "number"
    ) {
        const weightedVariance =
            ((n - 1) * sampleVarianceX + (m - 1) * sampleVarianceY) /
            (n + m - 2);

        return (
            (meanX - meanY - difference) /
            Math.sqrt(weightedVariance * (1 / n + 1 / m))
        );
    }
}

export default tTestTwoSample;

<MSG> Improve documentation quality

<DFF> @@ -23,6 +23,11 @@ var sampleVariance = require('./sample_variance');
  * `sampleX` and `sampleY` are equal to each other.
  *
  * Depends on `sampleVariance()` and `mean()`
+ *
+ * @param {Array<number>} sampleX
+ * @param {Array<number>} sampleY
+ * @param {number} [difference=0]
+ * @returns {number}
  */
 function tTestTwoSample(sampleX, sampleY, difference) {
     var n = sampleX.length,

{'addition_count': 5, 'commit_subject': 'Improve documentation quality', 'deletion_count': 0, 'file_extension': '.js', 'lang': 'js', 'license': 'isc', 'repo_name': 'simple-statistics/simple-statistics'}