tachometer/lib/stats.js

"use strict";
/**
 * @license
 * Copyright (c) 2019 The Polymer Project Authors. All rights reserved.
 * This code may only be used under the BSD style license found at
 * http://polymer.github.io/LICENSE.txt The complete set of authors may be found
 * at http://polymer.github.io/AUTHORS.txt The complete set of contributors may
 * be found at http://polymer.github.io/CONTRIBUTORS.txt Code distributed by
 * Google as part of the polymer project is also subject to an additional IP
 * rights grant found at http://polymer.github.io/PATENTS.txt
 */
Object.defineProperty(exports, "__esModule", { value: true });
exports.computeDifference = exports.computeDifferences = exports.horizonsResolved = exports.intervalContains = exports.summaryStats = void 0;
const jstat = require('jstat'); // TODO Contribute typings.
function summaryStats(data) {
    const size = data.length;
    const sum = sumOf(data);
    const mean = sum / size;
    const squareResiduals = data.map((val) => (val - mean) ** 2);
    // n - 1 due to https://en.wikipedia.org/wiki/Bessel%27s_correction
    const variance = sumOf(squareResiduals) / (size - 1);
    const stdDev = Math.sqrt(variance);
    return {
        size,
        mean,
        meanCI: confidenceInterval95(samplingDistributionOfTheMean({ mean, variance }, size), size),
        variance,
        standardDeviation: stdDev,
        // aka coefficient of variation
        relativeStandardDeviation: stdDev / mean,
    };
}
exports.summaryStats = summaryStats;
/**
 * Compute a 95% confidence interval for the given distribution.
 */
function confidenceInterval95({ mean, variance }, size) {
    // http://www.stat.yale.edu/Courses/1997-98/101/confint.htm
    const t = jstat.studentt.inv(1 - (.05 / 2), size - 1);
    const stdDev = Math.sqrt(variance);
    const margin = t * stdDev;
    return {
        low: mean - margin,
        high: mean + margin,
    };
}
/**
 * Return whether the given confidence interval contains a value.
 */
function intervalContains(interval, value) {
    return value >= interval.low && value <= interval.high;
}
exports.intervalContains = intervalContains;
/**
 * Return whether all difference confidence intervals are unambiguously located
 * on one side or the other of all given horizon values.
 *
 * For example, given the horizons 0 and 1:
 *
 *    <--->                   true
 *        <--->               false
 *            <--->           true
 *                <--->       false
 *                    <--->   true
 *        <----------->       false
 *
 *  |-------|-------|-------| ms difference
 * -1       0       1       2
 */
function horizonsResolved(resultStats, horizons) {
    for (const { differences } of resultStats) {
        if (differences === undefined) {
            continue;
        }
        // TODO We may want to offer more control over which particular set of
        // differences we care about resolving. For the moment, a horizon of 1%
        // means we'll try to resolve a 1% difference pairwise in both directions.
        for (const diff of differences) {
            if (diff === null) {
                continue;
            }
            for (const horizon of horizons.absolute) {
                if (intervalContains(diff.absolute, horizon)) {
                    return false;
                }
            }
            for (const horizon of horizons.relative) {
                if (intervalContains(diff.relative, horizon)) {
                    return false;
                }
            }
        }
    }
    return true;
}
exports.horizonsResolved = horizonsResolved;
function sumOf(data) {
    return data.reduce((acc, cur) => acc + cur);
}
/**
 * Given an array of results, return a new array of results where each result
 * has additional statistics describing how it compares to each other result.
 */
function computeDifferences(stats) {
    return stats.map((result) => {
        return Object.assign(Object.assign({}, result), { differences: stats.map((other) => other === result ?
                null :
                computeDifference(other.stats, result.stats)) });
    });
}
exports.computeDifferences = computeDifferences;
function computeDifference(a, b) {
    const meanA = samplingDistributionOfTheMean(a, a.size);
    const meanB = samplingDistributionOfTheMean(b, b.size);
    const diffAbs = samplingDistributionOfAbsoluteDifferenceOfMeans(meanA, meanB);
    const diffRel = samplingDistributionOfRelativeDifferenceOfMeans(meanA, meanB);
    // We're assuming sample sizes are equal. If they're not for some reason, be
    // conservative and use the smaller one for the t-distribution's degrees of
    // freedom (since that will lead to a wider confidence interval).
    const minSize = Math.min(a.size, b.size);
    return {
        absolute: confidenceInterval95(diffAbs, minSize),
        relative: confidenceInterval95(diffRel, minSize),
    };
}
exports.computeDifference = computeDifference;
/**
 * Estimates the sampling distribution of the mean. This models the distribution
 * of the means that we would compute under repeated samples of the given size.
 */
function samplingDistributionOfTheMean(dist, sampleSize) {
    // http://onlinestatbook.com/2/sampling_distributions/samp_dist_mean.html
    // http://www.stat.yale.edu/Courses/1997-98/101/sampmn.htm
    return {
        mean: dist.mean,
        // Error shrinks as sample size grows.
        variance: dist.variance / sampleSize,
    };
}
/**
 * Estimates the sampling distribution of the difference of means (b-a). This
 * models the distribution of the difference between two means that we would
 * compute under repeated samples under the given two sampling distributions of
 * means.
 */
function samplingDistributionOfAbsoluteDifferenceOfMeans(a, b) {
    // http://onlinestatbook.com/2/sampling_distributions/samplingdist_diff_means.html
    // http://www.stat.yale.edu/Courses/1997-98/101/meancomp.htm
    return {
        mean: b.mean - a.mean,
        // The error from both input sampling distributions of means accumulate.
        variance: a.variance + b.variance,
    };
}
/**
 * Estimates the sampling distribution of the relative difference of means
 * ((b-a)/a). This models the distribution of the relative difference between
 * two means that we would compute under repeated samples under the given two
 * sampling distributions of means.
 */
function samplingDistributionOfRelativeDifferenceOfMeans(a, b) {
    // http://blog.analytics-toolkit.com/2018/confidence-intervals-p-values-percent-change-relative-difference/
    // Note that the above article also prevents an alternative calculation for a
    // confidence interval for relative differences, but the one chosen here is
    // is much simpler and passes our stochastic tests, so it seems sufficient.
    return {
        mean: (b.mean - a.mean) / a.mean,
        variance: (a.variance * b.mean ** 2 + b.variance * a.mean ** 2) / a.mean ** 4,
    };
}
//# sourceMappingURL=stats.js.map