automatic color identity scale (#673)

* automatic color identity scale

* only identity if all values are colors (#676)

* only identity if all values are colors

* comments

* don’t use identity if scheme or range

* comments on scale type inference

* DRY

* Update README

Author: mbostock

README.md

@@ -145,9 +145,9 @@ Plot.plot({
 })
 ```
 
-Plot supports many scale types. Some scale types are for quantitative data — values that can be added or subtracted, such as temperature or time. Other scale types are for ordinal or categorical data — unquantifiable values that can only be ordered, such as t-shirt sizes, or values with no inherent order that can only be tested for equality, such as types of fruit. Some scale types are further intended for specific visual encodings — for example, as [position](#position-options) or [color](#color-options).
+Plot supports many scale types. Some scale types are for quantitative data: values that can be added or subtracted, such as temperature or time. Other scale types are for ordinal or categorical data: unquantifiable values that can only be ordered, such as t-shirt sizes, or values with no inherent order that can only be tested for equality, such as types of fruit. Some scale types are further intended for specific visual encodings: for example, as [position](#position-options) or [color](#color-options).
 
-You can set the scale type explicitly via the *scale*.**type** option, but typically the scale type is inferred automatically from data: strings and booleans imply an ordinal scale; dates imply a UTC scale; anything else is linear. Unless they represent text, we recommend explicitly converting strings to more specific types when loading data (*e.g.*, with d3.autoType or Observable’s FileAttachment). For simplicity’s sake, Plot assumes that data is consistently typed; type inference is based solely on the first non-null, non-undefined value. Certain mark types also imply a scale type; for example, the [Plot.barY](#plotbarydata-options) mark implies that the *x* scale is a *band* scale.
+You can set the scale type explicitly via the *scale*.**type** option, though typically the scale type is inferred automatically. Some marks mandate a particular scale type: for example, [Plot.barY](#plotbarydata-options) requires that the *x* scale is a *band* scale. Some scales have a default type: for example, the *radius* scale defaults to *sqrt* and the *opacity* scale defaults to *linear*. Most often, the scale type is inferred from associated data, pulled either from the domain (if specified) or from associated channels. A *color* scale defaults to *identity* if no range or scheme is specified and all associated defined values are valid CSS color strings. Otherwise, strings and booleans imply an ordinal scale; dates imply a UTC scale; and anything else is linear. Unless they represent text, we recommend explicitly converting strings to more specific types when loading data (*e.g.*, with d3.autoType or Observable’s FileAttachment). For simplicity’s sake, Plot assumes that data is consistently typed; type inference is based solely on the first non-null, non-undefined value.
 
 For quantitative data (*i.e.* numbers), a mathematical transform may be applied to the data by changing the scale type:
 
@@ -252,7 +252,7 @@ Similarly, the *y* and *fy* scales support asymmetric insets with:
 
 The inset scale options can provide “breathing room” to separate marks from axes or the plot’s edge. For example, in a scatterplot with a Plot.dot with the default 3-pixel radius and 1.5-pixel stroke width, an inset of 5 pixels prevents dots from overlapping with the axes. The *scale*.round option is useful for crisp edges by rounding to the nearest pixel boundary.
 
-In addition to the generic *ordinal* scale type, which requires an explicit output range value for each input domain value, Plot supports special *point* and *band* scale types for encoding ordinal data as position. These scale types accept a [*min*, *max*] range similar to quantitative scales, and divide this continuous interval into discrete points or bands based on the number of distinct values in the domain (*i.e.*, the domain’s cardinality). If the associated marks have no effective width along the ordinal dimension — such as a dot, rule, or tick — then use a *point* scale; otherwise, say for a bar, use a *band* scale. In the image below, the top *x*-scale is a *point* scale while the bottom *x*-scale is a *band* scale; see [Plot: Scales](https://observablehq.com/@observablehq/plot-scales) for an interactive version.
+In addition to the generic *ordinal* scale type, which requires an explicit output range value for each input domain value, Plot supports special *point* and *band* scale types for encoding ordinal data as position. These scale types accept a [*min*, *max*] range similar to quantitative scales, and divide this continuous interval into discrete points or bands based on the number of distinct values in the domain (*i.e.*, the domain’s cardinality). If the associated marks have no effective width along the ordinal dimension—such as a dot, rule, or tick—then use a *point* scale; otherwise, say for a bar, use a *band* scale. In the image below, the top *x*-scale is a *point* scale while the bottom *x*-scale is a *band* scale; see [Plot: Scales](https://observablehq.com/@observablehq/plot-scales) for an interactive version.
 
 <img src="./img/point-band.png" width="640" height="144" alt="point and band scales">
 
@@ -287,7 +287,7 @@ Top-level options are also supported as shorthand: **grid** (for *x* and *y* onl
 
 ### Color options
 
-The normal scale types — *linear*, *sqrt*, *pow*, *log*, *symlog*, and *ordinal* — can be used to encode color. In addition, Plot supports special scale types for color:
+The normal scale types—*linear*, *sqrt*, *pow*, *log*, *symlog*, and *ordinal*—can be used to encode color. In addition, Plot supports special scale types for color:
 
 * *categorical* - equivalent to *ordinal*, but defaults to the *tableau10* scheme
 * *sequential* - equivalent to *linear*
@@ -986,7 +986,7 @@ The following channels are optional:
 
 Typically either **x1** and **x2** are specified, or **y1** and **y2**, or both.
 
-If an **interval** is specified, such as d3.utcDay, **x1** and **x2** can be derived from **x**: *interval*.floor(*x*) is invoked for each *x* to produce *x1*, and *interval*.offset(*x1*) is invoked for each *x1* to produce *x2*. The same is true for *y*, *y1*, and *y2*, respectively. If the interval is specified as a number *n*, *x1* and *x2* are taken as the two consecutive multiples of *n* that bracket *x*. The interval may be specified either as as {x, interval} or x: {value, interval}—typically to apply different intervals to x and y.
+If an **interval** is specified, such as d3.utcDay, **x1** and **x2** can be derived from **x**: *interval*.floor(*x*) is invoked for each *x* to produce *x1*, and *interval*.offset(*x1*) is invoked for each *x1* to produce *x2*. The same is true for *y*, *y1*, and *y2*, respectively. If the interval is specified as a number *n*, *x1* and *x2* are taken as the two consecutive multiples of *n* that bracket *x*. The interval may be specified either as as {x, interval} or x: {value, interval} to apply different intervals to x and y.
 
 The rect mark supports the [standard mark options](#marks), including insets and rounded corners. The **stroke** defaults to none. The **fill** defaults to currentColor if the stroke is none, and to none otherwise.
 
@@ -1269,7 +1269,7 @@ Filters the data given the specified *test*. The test can be given as an accesso
 
 [<img src="./img/bin.png" width="320" height="198" alt="a histogram of athletes by weight">](https://observablehq.com/@observablehq/plot-bin)
 
-[Source](./src/transforms/bin.js) · [Examples](https://observablehq.com/@observablehq/plot-bin) · Aggregates continuous data — quantitative or temporal values such as temperatures or times — into discrete bins and then computes summary statistics for each bin such as a count or sum. The bin transform is like a continuous [group transform](#group) and is often used to make histograms. There are separate transforms depending on which dimensions need binning: [Plot.binX](#plotbinxoutputs-options) for *x*; [Plot.binY](#plotbinyoutputs-options) for *y*; and [Plot.bin](#plotbinoutputs-options) for both *x* and *y*.
+[Source](./src/transforms/bin.js) · [Examples](https://observablehq.com/@observablehq/plot-bin) · Aggregates continuous data—quantitative or temporal values such as temperatures or times—into discrete bins and then computes summary statistics for each bin such as a count or sum. The bin transform is like a continuous [group transform](#group) and is often used to make histograms. There are separate transforms depending on which dimensions need binning: [Plot.binX](#plotbinxoutputs-options) for *x*; [Plot.binY](#plotbinyoutputs-options) for *y*; and [Plot.bin](#plotbinoutputs-options) for both *x* and *y*.
 
 Given input *data* = [*d₀*, *d₁*, *d₂*, …], by default the resulting binned data is an array of arrays where each inner array is a subset of the input data [[*d₀₀*, *d₀₁*, …], [*d₁₀*, *d₁₁*, …], [*d₂₀*, *d₂₁*, …], …]. Each inner array is in input order. The outer array is in ascending order according to the associated dimension (*x* then *y*). Empty bins are skipped. By specifying a different aggregation method for the *data* output, as described below, you can change how the binned data is computed. The outputs may also include *filter* and *sort* options specified as aggregation methods, and a *reverse* option to reverse the order of generated bins. By default, empty bins are omitted, and non-empty bins are generated in ascending threshold order.
 
@@ -1407,7 +1407,7 @@ Bins on *y*. Also groups on *x* and first channel of *z*, *fill*, or *stroke*, i
 
 [<img src="./img/group.png" width="320" height="198" alt="a histogram of penguins by species">](https://observablehq.com/@observablehq/plot-group)
 
-[Source](./src/transforms/group.js) · [Examples](https://observablehq.com/@observablehq/plot-group) · Aggregates ordinal or categorical data — such as names — into groups and then computes summary statistics for each group such as a count or sum. The group transform is like a discrete [bin transform](#bin). There are separate transforms depending on which dimensions need grouping: [Plot.groupZ](#plotgroupzoutputs-options) for *z*; [Plot.groupX](#plotgroupxoutputs-options) for *x* and *z*; [Plot.groupY](#plotgroupyoutputs-options) for *y* and *z*; and [Plot.group](#plotgroupoutputs-options) for *x*, *y*, and *z*.
+[Source](./src/transforms/group.js) · [Examples](https://observablehq.com/@observablehq/plot-group) · Aggregates ordinal or categorical data—such as names—into groups and then computes summary statistics for each group such as a count or sum. The group transform is like a discrete [bin transform](#bin). There are separate transforms depending on which dimensions need grouping: [Plot.groupZ](#plotgroupzoutputs-options) for *z*; [Plot.groupX](#plotgroupxoutputs-options) for *x* and *z*; [Plot.groupY](#plotgroupyoutputs-options) for *y* and *z*; and [Plot.group](#plotgroupoutputs-options) for *x*, *y*, and *z*.
 
 Given input *data* = [*d₀*, *d₁*, *d₂*, …], by default the resulting grouped data is an array of arrays where each inner array is a subset of the input data [[*d₀₀*, *d₀₁*, …], [*d₁₀*, *d₁₁*, …], [*d₂₀*, *d₂₁*, …], …]. Each inner array is in input order. The outer array is in natural ascending order according to the associated dimension (*x* then *y*). Empty groups are skipped. By specifying a different aggregation method for the *data* output, as described below, you can change how the grouped data is computed. The outputs may also include *filter* and *sort* options specified as aggregation methods, and a *reverse* option to reverse the order of generated groups. By default, all (non-empty) groups are generated in ascending natural order.
 

src/options.js

@@ -25,9 +25,6 @@ export const first = d => d[0];
 export const second = d => d[1];
 export const constant = x => () => x;
 
-// A few extra color keywords not known to d3-color.
-const colors = new Set(["currentColor", "none"]);
-
 // Some channels may allow a string constant to be specified; to differentiate
 // string constants (e.g., "red") from named fields (e.g., "date"), this
 // function tests whether the given value is a CSS color string and returns a
@@ -37,7 +34,7 @@ const colors = new Set(["currentColor", "none"]);
 export function maybeColorChannel(value, defaultValue) {
   if (value === undefined) value = defaultValue;
   return value === null ? [undefined, "none"]
-    : typeof value === "string" && (colors.has(value) || color(value)) ? [undefined, value]
+    : isColor(value) ? [undefined, value]
     : [value, undefined];
 }
 
@@ -210,6 +207,38 @@ export function isNumeric(values) {
   }
 }
 
+export function isColors(values) {
+  for (const value of values) {
+    if (value == null) continue;
+    return isColor(value);
+  }
+}
+
+// Whereas isColors only tests the first defined value and returns undefined for
+// an empty array, this tests all defined values and only returns true if all of
+// them are valid colors. It also returns true for an empty array, and thus
+// should generally be used in conjunction with isColors.
+export function isAllColors(values) {
+  for (const value of values) {
+    if (value == null) continue;
+    if (!isColor(value)) return false;
+  }
+  return true;
+}
+
+// Mostly relies on d3-color, with a few extra color keywords. Currently this
+// strictly requires that the value be a string; we might want to apply string
+// coercion here, though note that d3-color instances would need to support
+// valueOf to work correctly with InternMap.
+export function isColor(value) {
+  if (!(typeof value === "string")) return false;
+  value = value.toLowerCase();
+  return value === "currentcolor" || value === "none" || color(value) !== null;
+}
+
+// Like a sort comparator, returns a positive value if the given array of values
+// is in ascending order, a negative value if the values are in descending
+// order. Assumes monotonicity; only tests the first and last values.
 export function order(values) {
   if (values == null) return;
   const first = values[0];

src/scales.js

@@ -1,5 +1,5 @@
 import {parse as isoParse} from "isoformat";
-import {isOrdinal, isTemporal, order} from "./options.js";
+import {isAllColors, isColors, isOrdinal, isTemporal, order} 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";
@@ -187,36 +187,67 @@ function Scale(key, channels = [], options = {}) {
   }
 }
 
-function inferScaleType(key, channels, {type, domain, range}) {
+function inferScaleType(key, channels, {type, domain, range, scheme}) {
+  // The facet scales are always band scales; this cannot be changed.
   if (key === "fx" || key === "fy") return "band";
-  if (type !== undefined) {
-    for (const {type: t} of channels) {
-      if (t !== undefined && type !== t) {
-        throw new Error(`scale incompatible with channel: ${type} !== ${t}`);
-      }
-    }
-    return type;
+
+  // If a channel dictates a scale type, make sure that it is consistent with
+  // the user-specified scale type (if any) and all other channels. For example,
+  // barY requires x to be a band scale and disallows any other scale type.
+  for (const {type: t} of channels) {
+    if (t === undefined) continue;
+    else if (type === undefined) type = t;
+    else if (type !== t) throw new Error(`scale incompatible with channel: ${type} !== ${t}`);
   }
-  if (registry.get(key) === radius) return "sqrt";
-  if (registry.get(key) === opacity || registry.get(key) === length) return "linear";
-  if (registry.get(key) === symbol) return "ordinal";
-  for (const {type} of channels) if (type !== undefined) return type;
-  if ((domain || range || []).length > 2) return asOrdinalType(key);
+
+  // If the scale, a channel, or user specified a (consistent) type, return it.
+  if (type !== undefined) return type;
+
+  // Some scales have default types.
+  const kind = registry.get(key);
+  if (kind === radius) return "sqrt";
+  if (kind === opacity || kind === length) return "linear";
+  if (kind === symbol) return "ordinal";
+
+  // For color scales, if no range or scheme is specified and all associated
+  // defined values (from the domain if present, and otherwise from channels)
+  // are valid colors, then default to the identity scale. This allows, for
+  // example, a fill channel to return literal colors; without this, the colors
+  // would be remapped to a categorical scheme!
+  if (kind === color
+    && range === undefined
+    && scheme === undefined
+    && (domain !== undefined
+      ? isColors(domain) && isAllColors(domain)
+      : channels.some(({value}) => value !== undefined && isColors(value))
+        && channels.every(({value}) => value === undefined || isAllColors(value)))) return "identity";
+
+  // If the domain or range has more than two values, assume it’s ordinal. You
+  // can still use a “piecewise” (or “polylinear”) scale, but you must set the
+  // type explicitly.
+  if ((domain || range || []).length > 2) return asOrdinalType(kind);
+
+  // Otherwise, infer the scale type from the data! Prefer the domain, if
+  // present, over channels. (The domain and channels should be consistently
+  // typed, and the domain is more explicit and typically much smaller.) We only
+  // check the first defined value for expedience and simplicitly; we expect
+  // that the types are consistent.
   if (domain !== undefined) {
-    if (isOrdinal(domain)) return asOrdinalType(key);
+    if (isOrdinal(domain)) return asOrdinalType(kind);
     if (isTemporal(domain)) return "utc";
     return "linear";
   }
+
   // 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(key);
+  if (values.some(isOrdinal)) return asOrdinalType(kind);
   if (values.some(isTemporal)) return "utc";
   return "linear";
 }
 
 // Positional scales default to a point scale instead of an ordinal scale.
-function asOrdinalType(key) {
-  switch (registry.get(key)) {
+function asOrdinalType(kind) {
+  switch (kind) {
     case position: return "point";
     case color: return "categorical";
     default: return "ordinal";