expose scales (#538)

* expose scales

* fix tests

* Update src/plot.js

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

* Update src/scales.js

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

* Update src/scales.js

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

* Update src/scales.js

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

* follow 3dbd159

* replace scale.family by tests
tiny difference with the parent commit: a non-position scale (such as opacity) can have an automatic label (including "%")

* only expose explicit scale options

* diverging-*

* reverse: true on diverging scales

* default type:
- "point" for positional scales
- "categorical" for color scales
- "ordinal" for other scales

* bugfix: when we create a finite range from a cyclical color scheme, the last color should not be the same as the first

* transform quantile scales into threshold scales ("internally", ie not only when exporting)

* scale type: "identity", and scale.transform

* fix reverse

* readme

* a bunch of unit tests

* prettier

* check that scales are reusable

* polylinear (aka piecewise linear) scale should work without specifying the domain

* utc

* braces

* fix test

* timezones… is this going to work?

* more utc

* polylinear color schemes

* polylinear scale with a color interpolate function (color scheme)

(seems like the most straightforward approach)

* fix polylinear scheme

* honor reverse: true, and accept a reversed (monotone-decreasing) domain.

* `zero: true` was not compatible with a polylinear domain.

(In practice, one probably wouldn’t try to use both options together. Still, looks safer.)

* simplify

* more tests for label (null, undefined)

* pass the original information about _reverse_

* expose round if not subsumed in interpolate (e.g., in point scales)

* use scale.range rather than scale.scale.range()

subsumes the range in *interpolate* for continuous color scales.

* prettier

* test diverging-* scales

* test diverging-log with negative values

* prefer left-hand-side label with ← for a reversed domain such as [100, 0]

this also fixes the issue of labelAnchor being wrong when exposing the scale, since reverse is sometimes subsumed in a reversal of the domain

* line

* Update src/scales.js

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

* clarify interpolate; expose clamp only if true

* force tests to pass

* first pass at cleaning tests

* run mocha once

* invert error logic

* jsdom test helper

* cleaner interpolate

* materialize clamp, interpolate; pow

* more test cleanup

* fix tests:
* sqrt is now pow with exponent .5
* clamp is now exposed when false

* fix polylinear

* fix interpolator test

* another test (piecewise + scheme + reverse)

* materialize round for band and point scales

* stricter validation of options

* more tests

* cyclical and sequential are linear

* more tests

* interpolate option for threshold and quantile scales

* map categorical to ordinal

* stricter validation for point and band scale options

* more tidying, tests

* test nonsense options

* piecewise scale tests

* categorical is promoted to ordinal

* consolidate ordinality tests

* fixes for diverging scales

* test for positive, not exactly one

* add mutation warning

* don’t mutate domain input

* don’t pass unnecessary options

* Update README

* tidy auto scale labels

* mutate warnings

* comment

* remove obsolete comment

* test ordinal transform

* transform and percent are not strictly quantitative

* handle percent, transform options generically

* don’t duplicate default interpolate

* identity accessor with interval transform

* fix default tick count for poly ranges

* robust scale order

* Update README

* fix scaleOrder for identity scales

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

Author: Fil

README.md

@@ -198,6 +198,23 @@ Plot.plot({
 })
 ```
 
+Scale definitions are exposed through the *plot*.**scale**(*name*) function of the returned plot.
+
+```js
+const plot = Plot.plot(…); // render a plot
+const color = plot.scale("color"); // retrieve the color scale object
+console.log(color.range); // inspect the color scale’s range, ["red", "blue"]
+```
+
+To reuse a scale across plots, pass the scale object into another plot specification:
+
+```js
+const plot1 = Plot.plot(…);
+const plot2 = Plot.plot({…, color: plot1.scale("color")});
+```
+
+The returned scale object represents the actual (or “materialized”) values encountered in the plot, including the domain, range, interpolate function, *etc.* The scale’s label, if any, is also returned; however, note that other axis properties are not currently exposed. The scale object is undefined if there is the associated plot has scale with the given *name*, and throws an error if the *name* is invalid (*i.e.*, not one of the known scale names: *x*, *y*, *fx*, *fy*, *r*, *color*, or *opacity*).
+
 ### Position options
 
 The position scales (*x*, *y*, *fx*, and *fy*) support additional options:

package.json

@@ -26,7 +26,7 @@
     "src/**/*.css"
   ],
   "scripts": {
-    "test": "mkdir -p test/output && mocha -r module-alias/register 'test/**/*-test.js' && mocha -r module-alias/register test/plot.js && eslint src test",
+    "test": "mkdir -p test/output && mocha -r module-alias/register 'test/**/*-test.js' test/plot.js && eslint src test",
     "prepublishOnly": "rm -rf dist && rollup -c",
     "postpublish": "git push && git push --tags",
     "dev": "snowpack dev"

src/axes.js

@@ -1,4 +1,7 @@
+import {extent} from "d3";
 import {AxisX, AxisY} from "./axis.js";
+import {isOrdinalScale, isTemporalScale, scaleOrder} from "./scales.js";
+import {position, registry} from "./scales/index.js";
 
 export function Axes(
   {x: xScale, y: yScale, fx: fxScale, fy: fyScale},
@@ -31,13 +34,13 @@ export function autoAxisTicks({x, y, fx, fy}, {x: xAxis, y: yAxis, fx: fxAxis, f
 
 function autoAxisTicksK(scale, axis, k) {
   if (axis.ticks === undefined) {
-    const [min, max] = scale.scale.range();
-    axis.ticks = Math.abs(max - min) / k;
+    const [min, max] = extent(scale.scale.range());
+    axis.ticks = (max - min) / k;
   }
 }
 
-// Mutates axis.{label,labelAnchor,labelOffset}!
-export function autoAxisLabels(channels, scales, {x, y, fx, fy}, dimensions) {
+// Mutates axis.{label,labelAnchor,labelOffset} and scale.label!
+export function autoScaleLabels(channels, scales, {x, y, fx, fy}, dimensions, options) {
   if (fx) {
     autoAxisLabelsX(fx, scales.fx, channels.get("fx"));
     if (fx.labelOffset === undefined) {
@@ -66,28 +69,47 @@ export function autoAxisLabels(channels, scales, {x, y, fx, fy}, dimensions) {
       y.labelOffset = y.axis === "left" ? marginLeft - facetMarginLeft : marginRight - facetMarginRight;
     }
   }
+  for (const [key, type] of registry) {
+    if (type !== position && scales[key]) { // not already handled above
+      autoScaleLabel(key, scales[key], channels.get(key), options[key]);
+    }
+  }
 }
 
+// Mutates axis.labelAnchor, axis.label, scale.label!
 function autoAxisLabelsX(axis, scale, channels) {
   if (axis.labelAnchor === undefined) {
-    axis.labelAnchor = scale.type === "ordinal" ? "center"
-      : scale.reverse ? "left"
+    axis.labelAnchor = isOrdinalScale(scale) ? "center"
+      : scaleOrder(scale) < 0 ? "left"
       : "right";
   }
   if (axis.label === undefined) {
     axis.label = inferLabel(channels, scale, axis, "x");
   }
+  scale.label = axis.label;
 }
 
+// Mutates axis.labelAnchor, axis.label, scale.label!
 function autoAxisLabelsY(axis, opposite, scale, channels) {
   if (axis.labelAnchor === undefined) {
-    axis.labelAnchor = scale.type === "ordinal" ? "center"
-      : opposite && opposite.axis === "top" ? "bottom" // TODO scale.reverse?
+    axis.labelAnchor = isOrdinalScale(scale) ? "center"
+      : opposite && opposite.axis === "top" ? "bottom" // TODO scaleOrder?
       : "top";
   }
   if (axis.label === undefined) {
     axis.label = inferLabel(channels, scale, axis, "y");
   }
+  scale.label = axis.label;
+}
+
+// Mutates scale.label!
+function autoScaleLabel(key, scale, channels, options) {
+  if (options) {
+    scale.label = options.label;
+  }
+  if (scale.label === undefined) {
+    scale.label = inferLabel(channels, scale, null, key);
+  }
 }
 
 // Channels can have labels; if all the channels for a given scale are
@@ -102,17 +124,19 @@ function inferLabel(channels = [], scale, axis, key) {
     else if (candidate !== label) return;
   }
   if (candidate !== undefined) {
-    const {percent, reverse} = scale;
     // Ignore the implicit label for temporal scales if it’s simply “date”.
-    if (scale.type === "temporal" && /^(date|time|year)$/i.test(candidate)) return;
-    if (scale.type !== "ordinal" && (key === "x" || key === "y")) {
-      if (percent) candidate = `${candidate} (%)`;
-      if (axis.labelAnchor === "center") {
-        candidate = `${candidate} →`;
-      } else if (key === "x") {
-        candidate = reverse ? `← ${candidate}` : `${candidate} →`;
-      } else {
-        candidate = `${reverse ? "↓ " : "↑ "}${candidate}`;
+    if (isTemporalScale(scale) && /^(date|time|year)$/i.test(candidate)) return;
+    if (!isOrdinalScale(scale)) {
+      if (scale.percent) candidate = `${candidate} (%)`;
+      if (key === "x" || key === "y") {
+        const order = scaleOrder(scale);
+        if (order) {
+          if (key === "x" || (axis && axis.labelAnchor === "center")) {
+            candidate = key === "x" === order < 0 ? `← ${candidate}` : `${candidate} →`;
+          } else {
+            candidate = `${order < 0 ? "↑ " : "↓ "}${candidate}`;
+          }
+        }
       }
     }
   }

src/marks/area.js

@@ -3,6 +3,7 @@ import {Curve} from "../curve.js";
 import {defined} from "../defined.js";
 import {Mark, indexOf, maybeZ} from "../mark.js";
 import {applyDirectStyles, applyIndirectStyles, applyTransform, applyGroupedChannelStyles} from "../style.js";
+import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
 
 const defaults = {
@@ -54,9 +55,9 @@ export function area(data, options) {
 }
 
 export function areaX(data, {y = indexOf, ...options} = {}) {
-  return new Area(data, maybeStackX({...options, y1: y, y2: undefined}));
+  return new Area(data, maybeStackX(maybeIdentityX({...options, y1: y, y2: undefined})));
 }
 
 export function areaY(data, {x = indexOf, ...options} = {}) {
-  return new Area(data, maybeStackY({...options, x1: x, x2: undefined}));
+  return new Area(data, maybeStackY(maybeIdentityY({...options, x1: x, x2: undefined})));
 }

src/marks/bar.js

@@ -3,6 +3,7 @@ import {filter} from "../defined.js";
 import {Mark, number} from "../mark.js";
 import {isCollapsed} from "../scales.js";
 import {applyDirectStyles, applyIndirectStyles, applyTransform, impliedString, applyAttr, applyChannelStyles} from "../style.js";
+import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeIntervalX, maybeIntervalY} from "../transforms/interval.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
 
@@ -117,9 +118,9 @@ export class BarY extends AbstractBar {
 }
 
 export function barX(data, options) {
-  return new BarX(data, maybeStackX(maybeIntervalX(options)));
+  return new BarX(data, maybeStackX(maybeIntervalX(maybeIdentityX(options))));
 }
 
 export function barY(data, options) {
-  return new BarY(data, maybeStackY(maybeIntervalY(options)));
+  return new BarY(data, maybeStackY(maybeIntervalY(maybeIdentityY(options))));
 }

src/marks/rect.js

@@ -3,6 +3,7 @@ import {filter} from "../defined.js";
 import {Mark, number} from "../mark.js";
 import {isCollapsed} from "../scales.js";
 import {applyDirectStyles, applyIndirectStyles, applyTransform, impliedString, applyAttr, applyChannelStyles} from "../style.js";
+import {maybeIdentityX, maybeIdentityY} from "../transforms/identity.js";
 import {maybeIntervalX, maybeIntervalY} from "../transforms/interval.js";
 import {maybeStackX, maybeStackY} from "../transforms/stack.js";
 
@@ -69,9 +70,9 @@ export function rect(data, options) {
 }
 
 export function rectX(data, options) {
-  return new Rect(data, maybeStackX(maybeIntervalY(options)));
+  return new Rect(data, maybeStackX(maybeIntervalY(maybeIdentityX(options))));
 }
 
 export function rectY(data, options) {
-  return new Rect(data, maybeStackY(maybeIntervalX(options)));
+  return new Rect(data, maybeStackY(maybeIntervalX(maybeIdentityY(options))));
 }

src/plot.js

@@ -1,8 +1,8 @@
 import {create} from "d3";
-import {Axes, autoAxisTicks, autoAxisLabels} from "./axes.js";
+import {Axes, autoAxisTicks, autoScaleLabels} from "./axes.js";
 import {facets} from "./facet.js";
 import {markify} from "./mark.js";
-import {Scales, autoScaleRange, applyScales} from "./scales.js";
+import {Scales, autoScaleRange, applyScales, exposeScales, isOrdinalScale} from "./scales.js";
 import {filterStyles, offset} from "./style.js";
 
 export function plot(options = {}) {
@@ -50,8 +50,8 @@ export function plot(options = {}) {
   const dimensions = Dimensions(scaleDescriptors, axes, options);
 
   autoScaleRange(scaleDescriptors, dimensions);
+  autoScaleLabels(scaleChannels, scaleDescriptors, axes, dimensions, options);
   autoAxisTicks(scaleDescriptors, axes);
-  autoAxisLabels(scaleChannels, scaleDescriptors, axes, dimensions);
 
   // Normalize the options.
   options = {...scaleDescriptors, ...dimensions};
@@ -90,11 +90,15 @@ export function plot(options = {}) {
   }
 
   // Wrap the plot in a figure with a caption, if desired.
-  if (caption == null) return svg;
-  const figure = document.createElement("figure");
-  figure.appendChild(svg);
-  const figcaption = figure.appendChild(document.createElement("figcaption"));
-  figcaption.appendChild(caption instanceof Node ? caption : document.createTextNode(caption));
+  let figure = svg;
+  if (caption != null) {
+    figure = document.createElement("figure");
+    figure.appendChild(svg);
+    const figcaption = figure.appendChild(document.createElement("figcaption"));
+    figcaption.appendChild(caption instanceof Node ? caption : document.createTextNode(caption));
+  }
+
+  figure.scale = exposeScales(scaleDescriptors);
   return figure;
 }
 
@@ -141,6 +145,6 @@ function ScaleFunctions(scales) {
 
 function autoHeight({y, fy, fx}) {
   const nfy = fy ? fy.scale.domain().length : 1;
-  const ny = y ? (y.type === "ordinal" ? y.scale.domain().length : Math.max(7, 17 / nfy)) : 1;
+  const ny = y ? (isOrdinalScale(y) ? y.scale.domain().length : Math.max(7, 17 / nfy)) : 1;
   return !!(y || fy) * Math.max(1, Math.min(60, ny * nfy)) * 20 + !!fx * 30 + 60;
 }