Quantize scales

Quantize scales are similar to linear scales, except they use a discrete rather than continuous range. The continuous input domain is divided into uniform segments based on the number of values in (i.e., the cardinality of) the output range. Each range value y can be expressed as a quantized linear function of the domain value x: y = m round(x) + b. See the quantized choropleth for an example.

scaleQuantize(domain, range)

Examples · Source · Constructs a new quantize scale with the specified domain and range.

const color = d3.scaleQuantize([0, 100], d3.schemeBlues[9]);

If either domain or range is not specified, each defaults to [0, 1].

const color = d3.scaleQuantize(d3.schemeBlues[9]);

quantize(value)

Examples · Source · Given a value in the input domain, returns the corresponding value in the output range. For example, to apply a color encoding:

const color = d3.scaleQuantize([0, 1], ["brown", "steelblue"]);
color(0.49); // "brown"
color(0.51); // "steelblue"

Or dividing the domain into three equally-sized parts with different range values to compute an appropriate stroke width:

const width = d3.scaleQuantize([10, 100], [1, 2, 4]);
width(20); // 1
width(50); // 2
width(80); // 4

quantize.invertExtent(value)

Examples · Source · Returns the extent of values in the domain [x0, x1] for the corresponding value in the range: the inverse of quantize. This method is useful for interaction, say to determine the value in the domain that corresponds to the pixel location under the mouse.

const width = d3.scaleQuantize([10, 100], [1, 2, 4]);
width.invertExtent(2); // [40, 70]

quantize.domain(domain)

Examples · Source · If domain is specified, sets the scale’s domain to the specified two-element array of numbers.

const color = d3.scaleQuantize(d3.schemeBlues[9]);
color.domain([0, 100]);

If the elements in the given array are not numbers, they will be coerced to numbers. The numbers must be in ascending order or the behavior of the scale is undefined.

If domain is not specified, returns the scale’s current domain.

color.domain() // [0, 100]

quantize.range(range)

Examples · Source · If range is specified, sets the scale’s range to the specified array of values.

const color = d3.scaleQuantize();
color.range(d3.schemeBlues[5]);

The array may contain any number of discrete values. The elements in the given array need not be numbers; any value or type will work.

If range is not specified, returns the scale’s current range.

color.range() // ["#eff3ff", "#bdd7e7", "#6baed6", "#3182bd", "#08519c"]

quantize.thresholds()

Examples · Source · Returns the array of computed thresholds within the domain.

color.thresholds() // [0.2, 0.4, 0.6, 0.8]

The number of returned thresholds is one less than the length of the range: values less than the first threshold are assigned the first element in the range, whereas values greater than or equal to the last threshold are assigned the last element in the range.

quantize.copy()

Examples · Source · Returns an exact copy of this scale.

const c1 = d3.scaleQuantize(d3.schemeBlues[5]);
const c2 = c1.copy();

Changes to this scale will not affect the returned scale, and vice versa.