expose instantiated scales descriptors in the render API (#1810)

* expose instantiated scales descriptors in the render API
* more uniform handling of identity scales
* don’t expose domain and range for identity (yet)

---------

Co-authored-by: Mike Bostock <[email protected]>

src/plot.js

@@ -141,11 +141,11 @@ export function plot(options = {}) {
 
   // Initalize the scales and dimensions.
   const scaleDescriptors = createScales(addScaleChannels(channelsByScale, stateByMark, options), options);
-  const scales = createScaleFunctions(scaleDescriptors);
   const dimensions = createDimensions(scaleDescriptors, marks, options);
 
   autoScaleRange(scaleDescriptors, dimensions);
 
+  const scales = createScaleFunctions(scaleDescriptors);
   const {fx, fy} = scales;
   const subdimensions = fx || fy ? innerDimensions(scaleDescriptors, dimensions) : dimensions;
   const superdimensions = fx || fy ? actualDimensions(scales, dimensions) : dimensions;
@@ -221,9 +221,10 @@ export function plot(options = {}) {
     addScaleChannels(newChannelsByScale, stateByMark, options, (key) => newByScale.has(key));
     addScaleChannels(channelsByScale, stateByMark, options, (key) => newByScale.has(key));
     const newScaleDescriptors = inheritScaleLabels(createScales(newChannelsByScale, options), scaleDescriptors);
-    const newScales = createScaleFunctions(newScaleDescriptors);
+    const {scales: newExposedScales, ...newScales} = createScaleFunctions(newScaleDescriptors);
     Object.assign(scaleDescriptors, newScaleDescriptors);
     Object.assign(scales, newScales);
+    Object.assign(scales.scales, newExposedScales);
   }
 
   // Sort and filter the facets to match the fx and fy domains; this is needed
@@ -333,7 +334,7 @@ export function plot(options = {}) {
     if (caption != null) figure.append(createFigcaption(document, caption));
   }
 
-  figure.scale = exposeScales(scaleDescriptors);
+  figure.scale = exposeScales(scales.scales);
   figure.legend = exposeLegends(scaleDescriptors, context, options);
 
   const w = consumeWarnings();

src/scales.d.ts

@@ -161,9 +161,9 @@ export type ScaleName = "x" | "y" | "fx" | "fy" | "r" | "color" | "opacity" | "s
 
 /**
  * The instantiated scales’ apply functions; passed to marks and initializers
- * for rendering.
+ * for rendering. The scales property exposes all the scale definitions.
  */
-export type ScaleFunctions = {[key in ScaleName]?: (value: any) => any};
+export type ScaleFunctions = {[key in ScaleName]?: (value: any) => any} & {scales: {[key in ScaleName]?: Scale}};
 
 /**
  * The supported scale types. For quantitative data, one of:

src/scales.js

@@ -97,17 +97,19 @@ export function createScales(
   return scales;
 }
 
-export function createScaleFunctions(scales) {
-  return Object.fromEntries(
-    Object.entries(scales)
-      .filter(([, {scale}]) => scale) // drop identity scales
-      .map(([name, {scale, type, interval, label}]) => {
-        scale.type = type; // for axis
-        if (interval != null) scale.interval = interval; // for axis
-        if (label != null) scale.label = label; // for axis
-        return [name, scale];
-      })
-  );
+export function createScaleFunctions(descriptors) {
+  const scales = {};
+  const scaleFunctions = {scales};
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    const {scale, type, interval, label} = descriptor;
+    scales[key] = exposeScale(descriptor);
+    scaleFunctions[key] = scale;
+    // TODO: pass these properties, which are needed for axes, in the descriptor.
+    scale.type = type;
+    if (interval != null) scale.interval = interval;
+    if (label != null) scale.label = label;
+  }
+  return scaleFunctions;
 }
 
 // Mutates scale.range!
@@ -362,7 +364,7 @@ function createScale(key, channels = [], options = {}) {
     case "band":
       return createScaleBand(key, channels, options);
     case "identity":
-      return registry.get(key) === position ? createScaleIdentity() : {type: "identity"};
+      return createScaleIdentity(key);
     case undefined:
       return;
     default:
@@ -513,10 +515,10 @@ export function scale(options = {}) {
   return scale;
 }
 
-export function exposeScales(scaleDescriptors) {
+export function exposeScales(scales) {
   return (key) => {
     if (!registry.has((key = `${key}`))) throw new Error(`unknown scale: ${key}`);
-    return key in scaleDescriptors ? exposeScale(scaleDescriptors[key]) : undefined;
+    return scales[key];
   };
 }
 

src/scales/index.js

@@ -45,3 +45,7 @@ export const registry = new Map([
 export function isPosition(kind) {
   return kind === position || kind === projection;
 }
+
+export function hasNumericRange(kind) {
+  return kind === position || kind === radius || kind === length || kind === opacity;
+}

src/scales/quantitative.js

@@ -25,7 +25,7 @@ import {
 } from "d3";
 import {finite, negative, positive} from "../defined.js";
 import {arrayify, constant, maybeNiceInterval, maybeRangeInterval, orderof, slice} from "../options.js";
-import {color, length, opacity, radius, registry} from "./index.js";
+import {color, length, opacity, radius, registry, hasNumericRange} from "./index.js";
 import {ordinalRange, quantitativeScheme} from "./schemes.js";
 
 export const flip = (i) => (t) => i(1 - t);
@@ -257,8 +257,12 @@ function isOrdered(domain, sign) {
   return true;
 }
 
-export function createScaleIdentity() {
-  return {type: "identity", scale: scaleIdentity()};
+// For non-numeric identity scales such as color and symbol, we can’t use D3’s
+// identity scale because it coerces to number; and we can’t compute the domain
+// (and equivalently range) since we can’t know whether the values are
+// continuous or discrete.
+export function createScaleIdentity(key) {
+  return {type: "identity", scale: hasNumericRange(registry.get(key)) ? scaleIdentity() : (d) => d};
 }
 
 export function inferDomain(channels, f = finite) {

test/scales/scales-test.js

@@ -2102,6 +2102,66 @@ it("plot(…).scale(name).apply and invert return the expected functions", () =>
   ]);
 });
 
+it("Plot.plot passes render functions scale descriptors", async () => {
+  const seed = d3.randomLcg(42);
+  const x = d3.randomNormal.source(seed)();
+  Plot.plot({
+    marks: [
+      Plot.dotX({length: 10001}, {x, fill: seed}),
+      (index, {x, color, scales}) => {
+        assert.deepStrictEqual(Object.keys(scales), ["color", "x"]);
+        assert.strictEqual(x(0), 314.6324357568407);
+        assert.strictEqual(x(1), 400.26512486789505);
+        assert.strictEqual(color(0), "rgb(35, 23, 27)");
+        assert.strictEqual(color(1), "rgb(144, 12, 0)");
+        scaleEqual(scales.color, {
+          type: "linear",
+          domain: [0.0003394410014152527, 0.999856373295188],
+          range: [0, 1],
+          clamp: false,
+          interpolate: d3.interpolateTurbo
+        });
+        scaleEqual(scales.x, {
+          type: "linear",
+          domain: [-3.440653783215207, 3.5660162890264693],
+          range: [20, 620],
+          clamp: false,
+          interpolate: d3.interpolateNumber
+        });
+        return null;
+      }
+    ]
+  });
+});
+
+it("Plot.plot passes render functions re-initialized scale descriptors and functions", async () => {
+  const seed = d3.randomLcg(42);
+  const x = d3.randomNormal.source(seed)();
+  const y = d3.randomNormal.source(seed)();
+  Plot.plot({
+    marks: [
+      Plot.dot({length: 10001}, Plot.hexbin({fill: "count"}, {x, y})),
+      (index, {x, y, color, scales}) => {
+        assert.deepStrictEqual(Object.keys(scales), ["x", "y", "color"]);
+        assert.ok(Math.abs(x(0) - 351) < 1);
+        assert.ok(Math.abs(x(1) - 426) < 1);
+        assert.ok(Math.abs(y(0) - 196) < 1);
+        assert.ok(Math.abs(y(1) - 148) < 1);
+        assert.strictEqual(color(1), "rgb(35, 23, 27)");
+        assert.strictEqual(color(10), "rgb(72, 58, 164)");
+        scaleEqual(scales.color, {
+          type: "linear",
+          domain: [1, 161],
+          range: [0, 1],
+          clamp: false,
+          interpolate: d3.interpolateTurbo
+        });
+        return null;
+      }
+    ]
+  });
+});
+
 it("plot(…).scale(name) returns a deduplicated ordinal domain", () => {
   const letters = "abbbcaabbcc";
   const plot = Plot.dotX(letters).plot({x: {domain: letters}});