add more quantiles computation methods

Author: sgratzl

README.md

@@ -170,10 +170,18 @@ interface IArrayLinearScale {
     coef: number;
 
     /**
-     * the method to compute the quantiles. 7 and 'quantiles' refers to the type-7 method as used by R 'quantiles' method. 'hinges' and 'fivenum' refers to the method used by R 'boxplot.stats' method.
+     * the method to compute the quantiles.
+     *
+     * 7, 'quantiles': the type-7 method as used by R 'quantiles' method.
+     * 'hinges' and 'fivenum': the method used by R 'boxplot.stats' method.
+     * 'linear': the interpolation method 'linear' as used by 'numpy.percentile' function
+     * 'lower': the interpolation method 'lower' as used by 'numpy.percentile' function
+     * 'higher': the interpolation method 'higher' as used by 'numpy.percentile' function
+     * 'nearest': the interpolation method 'nearest' as used by 'numpy.percentile' function
+     * 'midpoint': the interpolation method 'midpoint' as used by 'numpy.percentile' function
      * @default 7
      */
-    quantiles: 7 | 'quantiles' | 'hinges' | 'fivenum' | ((sortedArr: number[]) => {min: number, q1: number, median: number, q3: number, max: number});
+    quantiles: 7 | 'quantiles' | 'hinges' | 'fivenum' | 'linear' | 'lower' | 'higher' | 'nearest' | 'midpoint' | ((sortedArr: number[]) => {min: number, q1: number, median: number, q3: number, max: number});
   };
 }
 ```

src/data.js

@@ -2,17 +2,20 @@
 
 import kde from '@sgratzl/science/src/stats/kde';
 
-// Uses R's quantile algorithm type=7.
-// https://en.wikipedia.org/wiki/Quantile#Quantiles_of_a_population
-export function quantilesType7(arr) {
+/**
+ * computes the boxplot stats using the given interpolation function if needed
+ * @param {number[]} arr sorted array of number
+ * @param {(i: number, j: number, fraction: number)} interpolate interpolation function
+ */
+function quantilesInterpolate(arr, interpolate) {
   const n1 = arr.length - 1;
   const compute = (q) => {
     const index = 1 + q * n1;
     const lo = Math.floor(index);
     const h = index - lo;
     const a = arr[lo - 1];
 
-    return h === 0 ? a : a + h * (arr[lo] - a);
+    return h === 0 ? a : interpolate(a, arr[lo], h);
   };
 
   return {
@@ -24,6 +27,50 @@ export function quantilesType7(arr) {
   };
 }
 
+/**
+ * Uses R's quantile algorithm type=7.
+ * https://en.wikipedia.org/wiki/Quantile#Quantiles_of_a_population
+ */
+export function quantilesType7(arr) {
+  return quantilesInterpolate(arr, (a, b, alpha) => a + alpha * (b - a));
+}
+
+/**
+ * ‘linear’: i + (j - i) * fraction, where fraction is the fractional part of the index surrounded by i and j.
+ * (same as type 7)
+ */
+export function quantilesLinear(arr) {
+  return quantilesInterpolate(arr, (i, j, fraction) => i + (j - i) * fraction);
+}
+
+/**
+ * ‘lower’: i.
+ */
+export function quantilesLower(arr) {
+  return quantilesInterpolate(arr, (i) => i);
+}
+
+/**
+ * 'higher': j.
+ */
+export function quantilesHigher(arr) {
+  return quantilesInterpolate(arr, (_, j) => j);
+}
+
+/**
+ * ‘nearest’: i or j, whichever is nearest
+ */
+export function quantilesNearest(arr) {
+  return quantilesInterpolate(arr, (i, j, fraction) => (fraction <= 0.5 ? i : j));
+}
+
+/**
+ * ‘midpoint’: (i + j) / 2
+ */
+export function quantilesMidpoint(arr) {
+  return quantilesInterpolate(arr, (i, j) => (i + j) * 0.5);
+}
+
 /**
  * The hinges equal the quartiles for odd n (where n <- length(x))
  * and differ for even n. Whereas the quartiles only equal observations
@@ -92,10 +139,28 @@ const defaultStatsOptions = {
   quantiles: 7
 };
 
+function determineQuantiles(q) {
+  if (typeof q === 'function') {
+    return q;
+  }
+  const lookup = {
+    hinges: fivenum,
+    fivenum: fivenum,
+    7: quantilesType7,
+    quantiles: quantilesType7,
+    linear: quantilesLinear,
+    lower: quantilesLower,
+    higher: quantilesHigher,
+    nearest: quantilesNearest,
+    midpoint: quantilesMidpoint
+  }
+  return lookup[q] || quantilesType7;
+}
+
 function determineStatsOptions(options) {
   const coef = options == null || typeof options.coef !== 'number' ? defaultStatsOptions.coef : options.coef;
   const q = options == null ? null : options.quantiles;
-  const quantiles = typeof q === 'function' ? q : (q === 'hinges' || q === 'fivenum' ? fivenum : quantilesType7);
+  const quantiles = determineQuantiles(q);
   return {
     coef,
     quantiles

src/data.spec.js

@@ -1,4 +1,4 @@
-import {quantilesType7, fivenum} from './data';
+import {quantilesType7, fivenum, quantilesNearest, quantilesHigher, quantilesLinear, quantilesLower, quantilesMidpoint} from './data';
 
 function asc(a, b) {
   return a - b;
@@ -72,6 +72,23 @@ describe('quantiles and fivenum', () => {
       expect(fivenum(arr)).toEqual(asB(5830.748, 6518.398999999999, 7459.0635, 13297.2845, 18882.492));
     });
   });
+});
 
-
+describe('numpy interpolation', () => {
+  const arr = [3.375, 3.75, 3.875, 3, 3, 3.5, 3.125, 3, 2.625, 3.375, 3].sort(asc);
+  it('linear', () => {
+    expect(quantilesLinear(arr).q3).toBe(3.475);
+  });
+  it('higher', () => {
+    expect(quantilesHigher(arr).q3).toBe(3.5);
+  });
+  it('lower', () => {
+    expect(quantilesLower(arr).q3).toBe(3.375);
+  });
+  it('nearest', () => {
+    expect(quantilesNearest(arr).q3).toBe(3.5);
+  });
+  it('midpoint', () => {
+    expect(quantilesMidpoint(arr).q3).toBe(3.4375);
+  });
 });