bin interval (#735)

* bin interval

* Update README

* backwards-compatible intervals

Author: mbostock

README.md

@@ -1423,6 +1423,7 @@ Plot.binX({y: "count", title: names => names.join("\n")}, {x: "economy (mpg)", t
 To control how the quantitative dimensions *x* and *y* are divided into bins, the following options are supported:
 
 * **thresholds** - the threshold values; see below
+* **interval** - an alternative method of specifying thresholds
 * **domain** - values outside the domain will be omitted
 * **cumulative** - if positive, each bin will contain all lesser bins
 
@@ -1445,7 +1446,9 @@ The **thresholds** option may be specified as a named method or a variety of oth
 * an interval or time interval (for temporal binning; see below)
 * a function that returns an array, count, or time interval
 
-If the **thresholds** option is specified as a function, it is passed three arguments: the array of input values, the domain minimum, and the domain maximum. If a number, [d3.ticks](https://github.com/d3/d3-array/blob/main/README.md#ticks) or [d3.utcTicks](https://github.com/d3/d3-time/blob/master/README.md#ticks) is used to choose suitable nice thresholds. If an interval, it must expose an *interval*.floor(*value*), *interval*.ceil(*value*), and *interval*.range(*start*, *stop*) methods. If the interval is a time interval such as d3.utcDay, or if the thresholds are specified as an array of dates, then the binned values are implicitly coerced to dates. Time intervals are intervals that are also functions that return a Date instance when called with no arguments.
+If the **thresholds** option is specified as a function, it is passed three arguments: the array of input values, the domain minimum, and the domain maximum. If a number, [d3.ticks](https://github.com/d3/d3-array/blob/main/README.md#ticks) or [d3.utcTicks](https://github.com/d3/d3-time/blob/master/README.md#ticks) is used to choose suitable nice thresholds. If an interval, it must expose an *interval*.floor(*value*), *interval*.ceil(*value*), *interval*.offset(*value*), and *interval*.range(*start*, *stop*) methods. If the interval is a time interval such as d3.utcDay, or if the thresholds are specified as an array of dates, then the binned values are implicitly coerced to dates. Time intervals are intervals that are also functions that return a Date instance when called with no arguments.
+
+If the **interval** option is used instead of **thresholds**, it may be either an interval, a time interval, or a number. If a number *n*, threshold values are consecutive multiples of *n* that span the domain; otherwise, the **interval** option is equivalent to the **thresholds** option. When the thresholds are specified as an interval, and the default **domain** is used, the domain will automatically be extended to start and end to align with the interval.
 
 The bin transform supports grouping in addition to binning: you can subdivide bins by up to two additional ordinal or categorical dimensions (not including faceting). If any of **z**, **fill**, or **stroke** is a channel, the first of these channels will be used to subdivide bins. Similarly, Plot.binX will group on **y** if **y** is not an output channel, and Plot.binY will group on **x** if **x** is not an output channel. For example, for a stacked histogram:
 

src/transforms/bin.js

@@ -4,6 +4,7 @@ import {coerceDate} from "../scales.js";
 import {basic} from "./basic.js";
 import {hasOutput, maybeEvaluator, maybeGroup, maybeOutput, maybeOutputs, maybeReduce, maybeSort, maybeSubgroup, reduceCount, reduceIdentity} from "./group.js";
 import {maybeInsetX, maybeInsetY} from "./inset.js";
+import {maybeInterval} from "./interval.js";
 
 // Group on {z, fill, stroke}, then optionally on y, then bin x.
 export function binX(outputs = {y: "count"}, options = {}) {
@@ -78,6 +79,7 @@ function binn(
     domain, // eslint-disable-line no-unused-vars
     cumulative, // eslint-disable-line no-unused-vars
     thresholds, // eslint-disable-line no-unused-vars
+    interval, // eslint-disable-line no-unused-vars
     ...options
   } = inputs;
   const [GZ, setGZ] = maybeLazyChannel(z);
@@ -152,17 +154,18 @@ function binn(
 }
 
 // Allow bin options to be specified as part of outputs; merge them into options.
-function mergeOptions({cumulative, domain, thresholds, ...outputs}, options) {
-  return [outputs, {cumulative, domain, thresholds, ...options}];
+function mergeOptions({cumulative, domain, thresholds, interval, ...outputs}, options) {
+  return [outputs, {cumulative, domain, thresholds, interval, ...options}];
 }
 
-function maybeBinValue(value, {cumulative, domain, thresholds}, defaultValue) {
+function maybeBinValue(value, {cumulative, domain, thresholds, interval}, defaultValue) {
   value = {...maybeValue(value)};
   if (value.domain === undefined) value.domain = domain;
   if (value.cumulative === undefined) value.cumulative = cumulative;
   if (value.thresholds === undefined) value.thresholds = thresholds;
+  if (value.interval === undefined) value.interval = interval;
   if (value.value === undefined) value.value = defaultValue;
-  value.thresholds = maybeThresholds(value.thresholds);
+  value.thresholds = maybeThresholds(value.thresholds, value.interval);
   return value;
 }
 
@@ -194,7 +197,18 @@ function maybeBin(options) {
       }
       bin.thresholds(t).domain([min, max]);
     } else {
-      bin.thresholds(thresholds).domain(domain);
+      let d = domain;
+      let t = thresholds;
+      if (isInterval(t)) {
+        let [min, max] = typeof d === "function" ? d(V) : d;
+        if (d === extent) {
+          min = t.floor(min);
+          max = t.offset(t.floor(max));
+          d = [min, max];
+        }
+        t = t.range(min, max);
+      }
+      bin.thresholds(t).domain(d);
     }
     let bins = bin(range(data)).map(binset);
     if (cumulative) bins = (cumulative < 0 ? bins.reverse() : bins).map(bincumset);
@@ -204,7 +218,10 @@ function maybeBin(options) {
   return bin;
 }
 
-function maybeThresholds(thresholds = thresholdAuto) {
+function maybeThresholds(thresholds, interval) {
+  if (thresholds === undefined) {
+    return interval === undefined ? thresholdAuto : maybeRangeInterval(interval);
+  }
   if (typeof thresholds === "string") {
     switch (thresholds.toLowerCase()) {
       case "freedman-diaconis": return thresholdFreedmanDiaconis;
@@ -217,6 +234,13 @@ function maybeThresholds(thresholds = thresholdAuto) {
   return thresholds; // pass array, count, or function to bin.thresholds
 }
 
+// Unlike the interval transform, we require a range method, too.
+function maybeRangeInterval(interval) {
+  interval = maybeInterval(interval);
+  if (!isInterval(interval)) throw new Error("invalid interval");
+  return interval;
+}
+
 function thresholdAuto(values, min, max) {
   return Math.min(200, thresholdScott(values, min, max));
 }

src/transforms/interval.js

@@ -1,15 +1,20 @@
+import {range} from "d3";
 import {labelof, maybeValue, valueof} from "../options.js";
 import {maybeInsetX, maybeInsetY} from "./inset.js";
 
 // TODO Allow the interval to be specified as a string, e.g. “day” or “hour”?
 // This will require the interval knowing the type of the associated scale to
 // chose between UTC and local time (or better, an explicit timeZone option).
-function maybeInterval(interval) {
+export function maybeInterval(interval) {
   if (interval == null) return;
   if (typeof interval === "number") {
     const n = interval;
     // Note: this offset doesn’t support the optional step argument for simplicity.
-    interval = {floor: d => n * Math.floor(d / n), offset: d => d + n};
+    return {
+      floor: d => n * Math.floor(d / n),
+      offset: d => d + n,
+      range: (lo, hi) => range(Math.ceil(lo / n), hi / n).map(x => n * x)
+    };
   }
   if (typeof interval.floor !== "function" || typeof interval.offset !== "function") throw new Error("invalid interval");
   return interval;

test/data/timestamps.csv

@@ -0,0 +1,56 @@
+timestamp
+2022-01-31T18:16:31.964Z
+2022-01-30T14:37:47.021Z
+2022-01-29T15:04:34.007Z
+2022-01-29T14:23:45.360Z
+2022-01-28T21:42:41.078Z
+2022-01-28T20:12:55.377Z
+2022-01-28T16:23:43.560Z
+2022-01-28T15:22:18.908Z
+2022-01-27T17:26:40.052Z
+2022-01-26T14:55:15.640Z
+2022-01-25T19:33:52.923Z
+2022-01-25T14:53:29.893Z
+2022-01-24T17:17:34.008Z
+2022-01-24T14:10:27.382Z
+2022-01-23T16:33:33.685Z
+2022-01-23T14:52:40.121Z
+2022-01-21T21:39:51.625Z
+2022-01-21T19:50:38.138Z
+2022-01-21T17:32:19.085Z
+2022-01-21T16:06:57.899Z
+2022-01-21T15:52:38.116Z
+2022-01-21T15:01:52.420Z
+2022-01-20T19:12:16.275Z
+2022-01-19T16:47:56.095Z
+2022-01-18T19:04:53.190Z
+2022-01-18T16:14:21.534Z
+2022-01-18T14:24:26.530Z
+2022-01-16T17:48:41.245Z
+2022-01-16T17:32:13.164Z
+2022-01-14T18:11:06.535Z
+2022-01-13T19:07:52.806Z
+2022-01-13T18:04:59.779Z
+2022-01-13T16:40:20.998Z
+2022-01-13T15:59:31.069Z
+2022-01-12T22:17:03.540Z
+2022-01-12T15:43:46.363Z
+2022-01-12T14:09:15.628Z
+2022-01-11T23:05:25.974Z
+2022-01-11T15:00:48.222Z
+2022-01-11T14:50:12.751Z
+2022-01-10T23:42:59.140Z
+2022-01-10T17:21:09.829Z
+2022-01-08T15:10:26.196Z
+2022-01-08T14:00:18.029Z
+2022-01-07T16:50:55.843Z
+2022-01-05T19:06:41.335Z
+2022-01-05T15:25:46.501Z
+2022-01-05T14:33:12.087Z
+2022-01-05T13:31:23.154Z
+2022-01-04T23:36:29.180Z
+2022-01-04T20:55:16.325Z
+2022-01-04T19:35:17.920Z
+2022-01-04T17:01:15.535Z
+2022-01-04T15:15:14.705Z
+2022-01-03T22:12:59.816Z

test/output/intradayHistogram.svg

@@ -61,6 +61,7 @@ export {default as industryUnemploymentShare} from "./industry-unemployment-shar
 export {default as industryUnemploymentStream} from "./industry-unemployment-stream.js";
 export {default as industryUnemploymentTrack} from "./industry-unemployment-track.js";
 export {default as infinityLog} from "./infinity-log.js";
+export {default as intradayHistogram} from "./intraday-histogram.js";
 export {default as learningPoverty} from "./learning-poverty.js";
 export {default as letterFrequencyBar} from "./letter-frequency-bar.js";
 export {default as letterFrequencyCloud} from "./letter-frequency-cloud.js";

test/plots/index.js

@@ -0,0 +1,11 @@
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+
+export default async function() {
+  const timestamps = await d3.csv("data/timestamps.csv", d3.autoType);
+  return Plot.plot({
+    marks: [
+      Plot.rectY(timestamps, Plot.binX({y: "count"}, {x: d => d.timestamp.getUTCHours(), interval: 1}))
+    ]
+  });
+}