coerce to date for temporal thresholds (#572)

* coerce to date for temporal thresholds

* Update README

* Update README

Author: mbostock

README.md

@@ -1178,10 +1178,10 @@ The **thresholds** option may be specified as a named method or a variety of oth
 * *sturges* - [Sturges’ formula](https://en.wikipedia.org/wiki/Histogram#Sturges.27_formula)
 * a count (hint) representing the desired number of bins
 * an array of *n* threshold values for *n* + 1 bins
-* a time interval (for temporal binning)
+* 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 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.
 
 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/scales.js

@@ -286,7 +286,7 @@ function coerceArray(array, coerce, type = Array) {
 // Unlike Mark’s number, here we want to convert null and undefined to NaN,
 // since the result will be stored in a Float64Array and we don’t want null to
 // be coerced to zero.
-function coerceNumber(x) {
+export function coerceNumber(x) {
   return x == null ? NaN : +x;
 }
 
@@ -296,7 +296,7 @@ function coerceNumber(x) {
 // it is still generally preferable to do date parsing yourself explicitly,
 // rather than rely on Plot.) Any non-string values are coerced to number first
 // and treated as milliseconds since UNIX epoch.
-function coerceDate(x) {
+export function coerceDate(x) {
   return x instanceof Date && !isNaN(x) ? x
     : typeof x === "string" ? isoParse(x)
     : x == null || isNaN(x = +x) ? undefined

src/transforms/bin.js

@@ -1,5 +1,6 @@
 import {bin as binner, extent, thresholdFreedmanDiaconis, thresholdScott, thresholdSturges, utcTickInterval} from "d3";
 import {valueof, range, identity, maybeLazyChannel, maybeTuple, maybeColor, maybeValue, mid, labelof, isTemporal} from "../mark.js";
+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";
@@ -177,13 +178,14 @@ function maybeBin(options) {
   if (options == null) return;
   const {value, cumulative, domain = extent, thresholds} = options;
   const bin = data => {
-    const V = valueof(data, value);
+    let V = valueof(data, value);
     const bin = binner().value(i => V[i]);
-    if (isTemporal(V)) {
+    if (isTemporal(V) || isTimeThresholds(thresholds)) {
+      V = V.map(coerceDate);
       let [min, max] = typeof domain === "function" ? domain(V) : domain;
-      let t = typeof thresholds === "function" && !isTimeInterval(thresholds) ? thresholds(V, min, max) : thresholds;
+      let t = typeof thresholds === "function" && !isInterval(thresholds) ? thresholds(V, min, max) : thresholds;
       if (typeof t === "number") t = utcTickInterval(min, max, t);
-      if (isTimeInterval(t)) {
+      if (isInterval(t)) {
         if (domain === extent) {
           min = t.floor(min);
           max = t.ceil(new Date(+max + 1));
@@ -219,7 +221,15 @@ function thresholdAuto(values, min, max) {
   return Math.min(200, thresholdScott(values, min, max));
 }
 
+function isTimeThresholds(t) {
+  return isTimeInterval(t) || t && t[Symbol.iterator] && isTemporal(t);
+}
+
 function isTimeInterval(t) {
+  return isInterval(t) && typeof t === "function" && t() instanceof Date;
+}
+
+function isInterval(t) {
   return t ? typeof t.range === "function" : false;
 }
 

test/output/untypedDateBin.svg

@@ -116,6 +116,7 @@ export {default as stargazersHourlyGroup} from "./stargazers-hourly-group.js";
 export {default as stocksIndex} from "./stocks-index.js";
 export {default as travelersYearOverYear} from "./travelers-year-over-year.js";
 export {default as uniformRandomDifference} from "./uniform-random-difference.js";
+export {default as untypedDateBin} from "./untyped-date-bin.js";
 export {default as usCongressAge} from "./us-congress-age.js";
 export {default as usCongressAgeGender} from "./us-congress-age-gender.js";
 export {default as usPopulationStateAge} from "./us-population-state-age.js";

test/plots/index.js

@@ -0,0 +1,15 @@
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+
+export default async function() {
+  const aapl = await d3.csv("data/aapl.csv");
+  return Plot.plot({
+    y: {
+      transform: d => d / 1e6
+    },
+    marks: [
+      Plot.rectY(aapl, Plot.binX({y: "sum"}, {x: "Date", thresholds: d3.utcMonth, y: "Volume"})),
+      Plot.ruleY([0])
+    ]
+  });
+}