quantileIndex, medianIndex

closes #140

Author: Fil

README.md

@@ -57,13 +57,17 @@ const m = d3.min(array);
 
 ## API Reference
 
-* [Statistics](#statistics)
-* [Search](#search)
-* [Transformations](#transformations)
-* [Iterables](#iterables)
-* [Sets](#sets)
-* [Bins](#bins)
-* [Interning](#interning)
+- [d3-array](#d3-array)
+  - [Installing](#installing)
+  - [API Reference](#api-reference)
+    - [Statistics](#statistics)
+    - [Search](#search)
+    - [Transformations](#transformations)
+    - [Iterables](#iterables)
+    - [Sets](#sets)
+    - [Bins](#bins)
+      - [Bin Thresholds](#bin-thresholds)
+    - [Interning](#interning)
 
 ### Statistics
 
@@ -117,6 +121,10 @@ Returns the mean of the given *iterable* of numbers. If the iterable contains no
 
 Returns the median of the given *iterable* of numbers using the [R-7 method](https://en.wikipedia.org/wiki/Quantile#Estimating_quantiles_from_a_sample). If the iterable contains no numbers, returns undefined. An optional *accessor* function may be specified, which is equivalent to calling Array.from before computing the median. This method ignores undefined and NaN values; this is useful for ignoring missing data.
 
+<a name="medianIndex" href="#medianIndex">#</a> d3.<b>medianIndex</b>(<i>array</i>, <i>p</i>[, <i>accessor</i>]) [Source](https://github.com/d3/d3-array/blob/main/src/median.js "Source")
+
+Similar to *median*, but returns the index of the element to the left of the median.
+
 <a name="cumsum" href="#cumsum">#</a> d3.<b>cumsum</b>(<i>iterable</i>[, <i>accessor</i>]) · [Source](https://github.com/d3/d3-array/blob/main/src/cumsum.js), [Examples](https://observablehq.com/@d3/d3-cumsum)
 
 Returns the cumulative sum of the given *iterable* of numbers, as a Float64Array of the same length. If the iterable contains no numbers, returns zeros. An optional *accessor* function may be specified, which is equivalent to calling Array.from before computing the cumulative sum. This method ignores undefined and NaN values; this is useful for ignoring missing data.
@@ -137,6 +145,10 @@ d3.quantile(a, 0.1); // 2
 
 An optional *accessor* function may be specified, which is equivalent to calling *array*.map(*accessor*) before computing the quantile.
 
+<a name="quantileIndex" href="#quantileIndex">#</a> d3.<b>quantileIndex</b>(<i>array</i>, <i>p</i>[, <i>accessor</i>]) [Source](https://github.com/d3/d3-array/blob/main/src/quantile.js "Source")
+
+Similar to *quantile*, but returns the index to the left of *p*.
+
 <a name="quantileSorted" href="#quantileSorted">#</a> d3.<b>quantileSorted</b>(<i>array</i>, <i>p</i>[, <i>accessor</i>]) · [Source](https://github.com/d3/d3-array/blob/main/src/quantile.js), [Examples](https://observablehq.com/@d3/d3-mean-d3-median-and-friends)
 
 Similar to *quantile*, but expects the input to be a **sorted** *array* of values. In contrast with *quantile*, the accessor is only called on the elements needed to compute the quantile.

src/index.js

@@ -17,15 +17,15 @@ export {default as thresholdSturges} from "./threshold/sturges.js";
 export {default as max} from "./max.js";
 export {default as maxIndex} from "./maxIndex.js";
 export {default as mean} from "./mean.js";
-export {default as median} from "./median.js";
+export {default as median, medianIndex} from "./median.js";
 export {default as merge} from "./merge.js";
 export {default as min} from "./min.js";
 export {default as minIndex} from "./minIndex.js";
 export {default as mode} from "./mode.js";
 export {default as nice} from "./nice.js";
 export {default as pairs} from "./pairs.js";
 export {default as permute} from "./permute.js";
-export {default as quantile, quantileSorted} from "./quantile.js";
+export {default as quantile, quantileIndex, quantileSorted} from "./quantile.js";
 export {default as quickselect} from "./quickselect.js";
 export {default as range} from "./range.js";
 export {default as rank} from "./rank.js";

src/median.js

@@ -1,5 +1,9 @@
-import quantile from "./quantile.js";
+import quantile, {quantileIndex} from "./quantile.js";
 
 export default function median(values, valueof) {
   return quantile(values, 0.5, valueof);
 }
+
+export function medianIndex(values, valueof) {
+  return quantileIndex(values, 0.5, valueof);
+}

src/quantile.js

@@ -27,3 +27,17 @@ export function quantileSorted(values, p, valueof = number) {
       value1 = +valueof(values[i0 + 1], i0 + 1, values);
   return value0 + (value1 - value0) * (i - i0);
 }
+
+export function quantileIndex(values, p, valueof) {
+  if (valueof) values = Float64Array.from(numbers(values, valueof));
+  const q = quantile(values, p);
+
+  let index, v = -Infinity;
+  for (let i = 0; i < values.length; i++) {
+    const x = values[i];
+    if (x <= q) {
+      if (x > v) index = i, v = x;
+    }
+  }
+  return index;
+}

test/median-test.js

@@ -1,5 +1,5 @@
 import assert from "assert";
-import {median} from "../src/index.js";
+import {median, medianIndex} from "../src/index.js";
 import {OneTimeNumber} from "./OneTimeNumber.js";
 
 it("median(array) returns the median value for numbers", () => {
@@ -98,6 +98,16 @@ it("median(array, f) uses the undefined context", () => {
   assert.deepStrictEqual(results, [undefined, undefined]);
 });
 
+it("medianIndex(array) returns the index", () => {
+  assert.deepEqual(medianIndex([1, 2]), 0);
+  assert.deepEqual(medianIndex([1, 2, 3]), 1);
+  assert.deepEqual(medianIndex([1, 3, 2]), 2);
+  assert.deepEqual(medianIndex([2, 3, 1]), 0);
+  assert.deepEqual(medianIndex([1]), 0);
+  assert.deepEqual(medianIndex([]), undefined);
+});
+
+
 function box(value) {
   return {value: value};
 }

test/quantile-test.js

@@ -1,5 +1,5 @@
 import assert from "assert";
-import {quantile, quantileSorted} from "../src/index.js";
+import {quantile, quantileIndex, quantileSorted} from "../src/index.js";
 
 it("quantileSorted(array, p) requires sorted numeric input, quantile doesn't", () => {
   assert.strictEqual(quantileSorted([1, 2, 3, 4], 0), 1);
@@ -83,6 +83,15 @@ it("quantile(array, p, f) observes the specified accessor", () => {
   assert.strictEqual(quantile([], 1, unbox), undefined);
 });
 
+it("quantileIndex(array) returns the index", () => {
+  assert.deepEqual(quantileIndex([1, 2], 0.2), 0);
+  assert.deepEqual(quantileIndex([1, 2, 3], 0.2), 0);
+  assert.deepEqual(quantileIndex([1, 3, 2], 0.2), 0);
+  assert.deepEqual(quantileIndex([2, 3, 1], 0.2), 2);
+  assert.deepEqual(quantileIndex([1], 0.2), 0);
+  assert.deepEqual(quantileIndex([], 0.2), undefined);
+});
+
 function box(value) {
   return {value: value};
 }