isYearIntegers (#2403)

* isYearIntegers

* lineY; inline raw

* year heuristic for ordinal scale, tip, too

* isYearInteger tests

* document year heuristic

Author: mbostock

docs/features/scales.md

@@ -167,6 +167,14 @@ Plot.plot({x: {type: "time", domain: [new Date(2021, 0, 1), new Date(2022, 0, 1)
 ```
 :::
 
+If the tick values are all integers between 1,500 and 2,500 (inclusive), Plot assumes the values represent years and formats ticks by default without thousand separators, such as 1996 instead of 1,996. You can explicitly suppress thousand separators with `tickFormat: "d"`, or enable them with `tickFormat: ",d"`. <VersionBadge pr="2403" />
+
+:::plot
+```js
+Plot.plot({x: {domain: [1992, 2003], grid: true}})
+```
+:::
+
 When plotting values that vary widely, such as the luminosity of stars in an [HR diagram](https://observablehq.com/@mbostock/hertzsprung-russell-diagram), a *log* scale may improve readability. Log scales default to base-10 ticks with SI-prefix notation.
 
 :::plot https://observablehq.com/@observablehq/plot-continuous-scales
@@ -294,6 +302,14 @@ Plot.plot({
 
 Position scales also have a **round** option which forces the scale to snap to integer pixels. This defaults to true for point and band scales, and false for quantitative scales. Use caution with high-cardinality ordinal domains (*i.e.*, a point or band scale used to encode many different values), as rounding can lead to “wasted” space or even zero-width bands.
 
+If the domain values are all integers between 1,500 and 2,500 (inclusive), Plot assumes the values represent years and formats ticks by default without thousand separators, such as 1996 instead of 1,996. You can explicitly suppress thousand separators with `tickFormat: "d"`, or enable them with `tickFormat: ",d"`. <VersionBadge pr="2403" />
+
+:::plot
+```js
+Plot.plot({x: {type: "band", domain: d3.range(1992, 2003), grid: true}})
+```
+:::
+
 ## Color scales
 
 While position is the most salient (and important) encoding, color matters too! The default quantitative color scale **type** is *linear*, and the default **scheme** is [*turbo*](https://ai.googleblog.com/2019/08/turbo-improved-rainbow-colormap-for.html). A wide variety of sequential, diverging, and cyclical schemes are supported, including ColorBrewer and [*viridis*](http://bids.github.io/colormap/).

src/marks/axis.js

@@ -3,7 +3,7 @@ import {formatDefault} from "../format.js";
 import {marks} from "../mark.js";
 import {radians} from "../math.js";
 import {arrayify, constant, identity, keyword, number, range, valueof} from "../options.js";
-import {isIterable, isNoneish, isTemporal, isInterval} from "../options.js";
+import {isIterable, isNoneish, isYearIntegers, isTemporal, isInterval} from "../options.js";
 import {maybeColorChannel, maybeNumberChannel, maybeRangeInterval} from "../options.js";
 import {inferScaleOrder} from "../scales.js";
 import {offset} from "../style.js";
@@ -670,6 +670,8 @@ export function inferTickFormat(scale, data, ticks, tickFormat, anchor) {
     ? tickFormat
     : tickFormat === undefined && data && isTemporal(data)
     ? inferTimeFormat(scale.type, data, anchor) ?? formatDefault
+    : tickFormat === undefined && data && isYearIntegers(data)
+    ? String
     : scale.tickFormat
     ? scale.tickFormat(typeof ticks === "number" ? ticks : null, tickFormat)
     : typeof tickFormat === "string" && scale.domain().length > 0

src/marks/tip.js

@@ -7,7 +7,7 @@ import {anchorX, anchorY} from "../interactions/pointer.js";
 import {Mark} from "../mark.js";
 import {maybeAnchor, maybeFrameAnchor, maybeTuple, number, string} from "../options.js";
 import {applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, impliedString} from "../style.js";
-import {identity, isIterable, isTemporal, isTextual} from "../options.js";
+import {identity, isIterable, isTemporal, isTextual, isYearIntegers} from "../options.js";
 import {inferTickFormat} from "./axis.js";
 import {applyIndirectTextStyles, defaultWidth, ellipsis, monospaceWidth} from "./text.js";
 import {cut, clipper, splitter, maybeTextOverflow} from "./text.js";
@@ -362,14 +362,19 @@ function getSourceChannels(channels, scales) {
   // Promote shorthand string formats, and materialize default formats.
   for (const key in sources) {
     const format = this.format[key];
+    const scale = scales[key];
+    const value = sources[key]?.value ?? scale?.domain() ?? [];
     if (typeof format === "string") {
-      const value = sources[key]?.value ?? scales[key]?.domain() ?? [];
       this.format[key] = (isTemporal(value) ? utcFormat : numberFormat)(format);
     } else if (format === undefined || format === true) {
       // For ordinal scales, the inferred tick format can be more concise, such
-      // as only showing the year for yearly data.
-      const scale = scales[key];
-      this.format[key] = scale?.bandwidth ? inferTickFormat(scale, scale.domain()) : formatDefault;
+      // as only showing the year for yearly data. Similarly if all the values
+      // look like years, we can avoid the thousands comma.
+      this.format[key] = scale?.bandwidth
+        ? inferTickFormat(scale, scale.domain())
+        : isYearIntegers(value)
+        ? String
+        : formatDefault;
     }
   }
 

src/options.js

@@ -513,6 +513,14 @@ export function isNumeric(values) {
   }
 }
 
+export function isYearIntegers(values) {
+  return isEvery(values, isYearInteger);
+}
+
+export function isYearInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && 1500 <= value && value <= 2500;
+}
+
 // Returns true if every non-null value in the specified iterable of values
 // passes the specified predicate, and there is at least one non-null value;
 // returns false if at least one non-null value does not pass the specified

test/options-test.js

@@ -1,5 +1,34 @@
 import {assert, it} from "vitest";
 import {identity, isNumericString, valueof} from "../src/options.js";
+import {isYearInteger, isYearIntegers} from "../src/options.js";
+
+it("isYearInteger returns true for integers in [1500, 2500]", () => {
+  assert.strictEqual(isYearInteger(1500), true);
+  assert.strictEqual(isYearInteger(1999), true);
+  assert.strictEqual(isYearInteger(2000), true);
+  assert.strictEqual(isYearInteger(2001), true);
+  assert.strictEqual(isYearInteger(2500), true);
+});
+
+it("isYearInteger returns false for non-integers, or numbers outside [1500, 2500]", () => {
+  assert.strictEqual(isYearInteger(-2000), false);
+  assert.strictEqual(isYearInteger(-1500), false);
+  assert.strictEqual(isYearInteger(0), false);
+  assert.strictEqual(isYearInteger("1000"), false);
+  assert.strictEqual(isYearInteger(null), false);
+  assert.strictEqual(isYearInteger(2000.5), false);
+  assert.strictEqual(isYearInteger(NaN), false);
+  assert.strictEqual(isYearInteger(undefined), false);
+});
+
+it("isYearIntegers requires every value to be a year integer", () => {
+  assert.strictEqual(isYearIntegers([]), undefined);
+  assert.strictEqual(isYearIntegers([1]), false);
+  assert.strictEqual(isYearIntegers([2000]), true);
+  assert.strictEqual(isYearIntegers([2000, 1]), false);
+  assert.strictEqual(isYearIntegers([2000, "2000"]), false);
+  assert.strictEqual(isYearIntegers([2000, 1999]), true);
+});
 
 it("isNumericString detects numeric strings", () => {
   assert.strictEqual(isNumericString(["42"]), true);