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) && 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 }