src/utils/StatisticUtils.ts

   1 import { isEmptyArray, isNullOrUndefined } from './Utils.js';
   2
   3 /**
   4  * Computes the average of the given data set.
   5  *
   6  * @param dataSet - Data set.
   7  * @returns The average of the given data set.
   8  * @internal
   9  */
  10 export const average = (dataSet: number[]): number => {
  11   if (Array.isArray(dataSet) && dataSet.length === 0) {
  12     return 0;
  13   }
  14   if (Array.isArray(dataSet) && dataSet.length === 1) {
  15     return dataSet[0];
  16   }
  17   return dataSet.reduce((accumulator, nb) => accumulator + nb, 0) / dataSet.length;
  18 };
  19
  20 /**
  21  * Computes the median of the given data set.
  22  *
  23  * @param dataSet - Data set.
  24  * @returns The median of the given data set.
  25  * @internal
  26  */
  27 export const median = (dataSet: number[]): number => {
  28   if (isEmptyArray(dataSet)) {
  29     return 0;
  30   }
  31   if (Array.isArray(dataSet) === true && dataSet.length === 1) {
  32     return dataSet[0];
  33   }
  34   const sortedDataSet = dataSet.slice().sort((a, b) => a - b);
  35   return (
  36     (sortedDataSet[(sortedDataSet.length - 1) >> 1] + sortedDataSet[sortedDataSet.length >> 1]) / 2
  37   );
  38 };
  39
  40 // TODO: use order statistics tree https://en.wikipedia.org/wiki/Order_statistic_tree
  41 export const nthPercentile = (dataSet: number[], percentile: number): number => {
  42   if (percentile < 0 && percentile > 100) {
  43     throw new RangeError('Percentile is not between 0 and 100');
  44   }
  45   if (isEmptyArray(dataSet)) {
  46     return 0;
  47   }
  48   const sortedDataSet = dataSet.slice().sort((a, b) => a - b);
  49   if (percentile === 0 || sortedDataSet.length === 1) {
  50     return sortedDataSet[0];
  51   }
  52   if (percentile === 100) {
  53     return sortedDataSet[sortedDataSet.length - 1];
  54   }
  55   const percentileIndexBase = (percentile / 100) * (sortedDataSet.length - 1);
  56   const percentileIndexInteger = Math.floor(percentileIndexBase);
  57   if (!isNullOrUndefined(sortedDataSet[percentileIndexInteger + 1])) {
  58     return (
  59       sortedDataSet[percentileIndexInteger] +
  60       (percentileIndexBase - percentileIndexInteger) *
  61         (sortedDataSet[percentileIndexInteger + 1] - sortedDataSet[percentileIndexInteger])
  62     );
  63   }
  64   return sortedDataSet[percentileIndexInteger];
  65 };
  66
  67 /**
  68  * Computes the sample standard deviation of the given data set.
  69  *
  70  * @param dataSet - Data set.
  71  * @param dataSetAverage - Average of the data set.
  72  * @returns The sample standard deviation of the given data set.
  73  * @see https://en.wikipedia.org/wiki/Unbiased_estimation_of_standard_deviation
  74  * @internal
  75  */
  76 export const stdDeviation = (
  77   dataSet: number[],
  78   dataSetAverage: number = average(dataSet),
  79 ): number => {
  80   if (isEmptyArray(dataSet)) {
  81     return 0;
  82   }
  83   if (Array.isArray(dataSet) && dataSet.length === 1) {
  84     return 0;
  85   }
  86   return Math.sqrt(
  87     dataSet.reduce((accumulator, num) => accumulator + Math.pow(num - dataSetAverage, 2), 0) /
  88       (dataSet.length - 1),
  89   );
  90 };