warnings!

Author: mbostock

src/options.js

@@ -1,3 +1,4 @@
+import {parse as isoParse} from "isoformat";
 import {color, descending} from "d3";
 import {symbolAsterisk, symbolDiamond2, symbolPlus, symbolSquare2, symbolTriangle2, symbolX as symbolTimes} from "d3";
 import {symbolCircle, symbolCross, symbolDiamond, symbolSquare, symbolStar, symbolTriangle, symbolWye} from "d3";
@@ -210,6 +211,17 @@ export function isTemporal(values) {
   }
 }
 
+// Are these strings that might represent dates? This is stricter than ISO 8601
+// because we want to ignore false positives on numbers; for example, the string
+// "1192" is more likely to represent a number than a date even though it is
+// valid ISO 8601 representing 1192-01-01.
+export function isTemporalString(values) {
+  for (const value of values) {
+    if (value == null) continue;
+    return typeof value === "string" && isNaN(value) && isoParse(value);
+  }
+}
+
 export function isNumeric(values) {
   for (const value of values) {
     if (value == null) continue;

src/plot.js

@@ -1,4 +1,4 @@
-import {create, cross, difference, groups, InternMap} from "d3";
+import {create, cross, difference, groups, InternMap, select} from "d3";
 import {Axes, autoAxisTicks, autoScaleLabels} from "./axes.js";
 import {Channel, channelSort} from "./channel.js";
 import {defined} from "./defined.js";
@@ -8,6 +8,7 @@ import {arrayify, isOptions, keyword, range, first, second, where} from "./optio
 import {Scales, ScaleFunctions, autoScaleRange, applyScales, exposeScales} from "./scales.js";
 import {applyInlineStyles, maybeClassName, styles} from "./style.js";
 import {basic} from "./transforms/basic.js";
+import {consumeWarnings} from "./warnings.js";
 
 export function plot(options = {}) {
   const {facet, style, caption, ariaLabel, ariaDescription} = options;
@@ -119,6 +120,19 @@ export function plot(options = {}) {
 
   figure.scale = exposeScales(scaleDescriptors);
   figure.legend = exposeLegends(scaleDescriptors, options);
+
+  const w = consumeWarnings();
+  if (w > 0) {
+    select(svg).append("text")
+        .attr("x", width)
+        .attr("y", 20)
+        .attr("dy", "-1em")
+        .attr("text-anchor", "end")
+        .text("⚠️")
+      .append("title")
+        .text(`${w.toLocaleString("en-US")} warning${w === 1 ? "" : "s"}. Please check the console.`);
+  }
+
   return figure;
 }
 

src/scales.js

@@ -1,10 +1,11 @@
 import {parse as isoParse} from "isoformat";
-import {isColor, isEvery, isOrdinal, isFirst, isSymbol, isTemporal, maybeSymbol, order} from "./options.js";
+import {isColor, isEvery, isOrdinal, isFirst, isSymbol, isTemporal, maybeSymbol, order, isTemporalString} from "./options.js";
 import {registry, color, position, radius, opacity, symbol, length} from "./scales/index.js";
 import {ScaleLinear, ScaleSqrt, ScalePow, ScaleLog, ScaleSymlog, ScaleQuantile, ScaleThreshold, ScaleIdentity} from "./scales/quantitative.js";
 import {ScaleDiverging, ScaleDivergingSqrt, ScaleDivergingPow, ScaleDivergingLog, ScaleDivergingSymlog} from "./scales/diverging.js";
 import {ScaleTime, ScaleUtc} from "./scales/temporal.js";
 import {ScaleOrdinal, ScalePoint, ScaleBand, ordinalImplicit} from "./scales/ordinal.js";
+import {warn} from "./warnings.js";
 
 export function Scales(channels, {
   inset: globalInset = 0,
@@ -133,6 +134,14 @@ export function normalizeScale(key, scale, hint) {
 
 function Scale(key, channels = [], options = {}) {
   const type = inferScaleType(key, channels, options);
+
+  // Warn for common misuse of implicit band scales.
+  if (options.type === undefined && type === "band") {
+    const values = channels.map(({value}) => value).filter(value => value !== undefined);
+    if (values.some(isTemporal)) warn(`Warning: some data associated with the ${key} scale are dates. Dates are typically associated with a "utc" or "time" scale rather than a "band" scale. If you are using a bar mark, you probably want to switch to a rect mark with the interval option; if you are using a group transform, you probably want to switch to a bin transform. If you intend to treat this data as ordinal, you can suppress this warning by setting the type of the ${key} scale to "band".`);
+    else if (values.some(isTemporalString)) warn(`Warning: some data associated with the ${key} scale are strings that appear to be dates (e.g., YYYY-MM-DD). If these strings represent dates, you should parse and convert them to Date objects. Dates are typically associated with a "utc" or "time" scale rather than a "band" scale. If you are using a bar mark, you probably want to switch to a rect mark with the interval option; if you are using a group transform, you probably want to switch to a bin transform. If you intend to treat this data as ordinal, you can suppress this warning by setting the type of the ${key} scale to "${typeof type === "symbol" ? type.description : type}".`);
+  }
+
   options.type = type; // Mutates input!
 
   // Once the scale type is known, coerce the associated channel values and any
@@ -246,7 +255,11 @@ function inferScaleType(key, channels, {type, domain, range, scheme}) {
 
   // If any channel is ordinal or temporal, it takes priority.
   const values = channels.map(({value}) => value).filter(value => value !== undefined);
-  if (values.some(isOrdinal)) return asOrdinalType(kind);
+  if (values.some(isOrdinal)) {
+    const type = asOrdinalType(kind);
+    if (values.some(isTemporalString)) warn(`Warning: some data associated with the ${key} scale are strings that appear to be dates (e.g., YYYY-MM-DD). If these strings represent dates, you should parse and convert them to Date objects. If you intend to treat this data as ordinal, you can suppress this warning by setting the type of the ${key} scale to "${typeof type === "symbol" ? type.description : type}".`);
+    return type;
+  }
   if (values.some(isTemporal)) return "utc";
   return "linear";
 }

src/warnings.js

@@ -0,0 +1,12 @@
+let warnings = 0;
+
+export function consumeWarnings() {
+  const w = warnings;
+  warnings = 0;
+  return w;
+}
+
+export function warn(message) {
+  console.warn(message);
+  ++warnings;
+}