src/utils/StatisticUtils.ts

   1 import { isEmptyArray } 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   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
  58   if (sortedDataSet[percentileIndexInteger + 1] != null) {
  59     return (
  60       sortedDataSet[percentileIndexInteger] +
  61       (percentileIndexBase - percentileIndexInteger) *
  62         (sortedDataSet[percentileIndexInteger + 1] - sortedDataSet[percentileIndexInteger])
  63     )
  64   }
  65   return sortedDataSet[percentileIndexInteger]
  66 }
  67
  68 /**
  69  * Computes the sample standard deviation of the given data set.
  70  *
  71  * @param dataSet - Data set.
  72  * @param dataSetAverage - Average of the data set.
  73  * @returns The sample standard deviation of the given data set.
  74  * @see https://en.wikipedia.org/wiki/Unbiased_estimation_of_standard_deviation
  75  * @internal
  76  */
  77 export const stdDeviation = (
  78   dataSet: number[],
  79   dataSetAverage: number = average(dataSet)
  80 ): number => {
  81   if (isEmptyArray(dataSet)) {
  82     return 0
  83   }
  84   if (Array.isArray(dataSet) && dataSet.length === 1) {
  85     return 0
  86   }
  87   return Math.sqrt(
  88     dataSet.reduce((accumulator, num) => accumulator + Math.pow(num - dataSetAverage, 2), 0) /
  89       (dataSet.length - 1)
  90   )
  91 }