Scales

Scales map data values (numbers, dates, categories, etc.) to visual values (pixels, colors, sizes). Scales are a fundamental building block of data visualization, as they determine the nature of visual encodings. Vega includes a range of scales for both continuous and discrete input data, and supports mappings for position, shape, size and color encodings.

To visualize scales, Vega specifications may include axes or legends. For more about supported color encodings, see the color scheme reference. Internally, Vega uses the scales provided by the d3-scale library; for more background see Introducing d3-scale by Mike Bostock.

Documentation Overview

• Scale Properties
• Scale Types
• Scale Domains
• Scale Ranges

Scale Properties

Properties shared across scale types.

Scale Types

• Quantitative Scales
  • linear
  • log
  • pow
  • sqrt
  • symlog
  • time
  • utc
  • sequential
• Discrete Scales
  • ordinal
  • band
  • point
• Discretizing Scales
  • quantile
  • quantize
  • threshold
  • bin-ordinal

Quantitative Scales

A quantitative scale maps a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). The available quantitative scale type values are linear, log, pow, sqrt, symlog, time and utc. All quantitative scales except for time and utc use a default domain of [0, 1] and default unit range [0, 1].

All quantitative scales support color-valued ranges, defined either as an array of color strings or as a scheme specification. If the domain includes two color values, a sequential color scale is used. If the domain includes three color values, a diverging color scale is used. For larger domain sizes, the domain and range should have the same number of values, over which piecewise interpolation will be applied.

Linear Scales

Linear scales (linear) are quantitative scales scales that preserve proportional differences. Each range value y can be expressed as a linear function of the domain value x: y = mx + b.

Logarithmic Scales

Log scales (log) are quantitative scales scales in which a logarithmic transform is applied to the input domain value before the output range value is computed. Log scales are particularly useful for plotting data that varies over multiple orders of magnitude. The mapping to the range value y can be expressed as a logarithmic function of the domain value x: y = m log(x) + b.

As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero. A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values. (For a negative domain, input and output values are implicitly multiplied by -1.) The behavior of the scale is undefined if you run a negative value through a log scale with a positive domain or vice versa.

Power Scales

Power scales (pow) are quantitative scales scales that apply an exponential transform to the input domain value before the output range value is computed. Each range value y can be expressed as a polynomial function of the domain value x: y = mx^k + b, where k is the exponent value. Power scales also support negative domain values, in which case the input value and the resulting output value are multiplied by -1.

Square Root Scales

Square root (sqrt) scales are a convenient shorthand for power scales with an exponent of 0.5, indicating a square root transform.

Symmetric Log Scales ≥ 5.0

Symmetric log scales (symlog) are quantitative scales scales that provide scaling similar to log scales, but supports non-positive numbers. Symlog scales are particularly useful for plotting data that varies over multiple orders of magnitude but includes negative- or zero-valued data. For more, see “A bi-symmetric log transformation for wide-range data” by Webber for more.

Time and UTC Scales

Time scales (time and utc) are quantitative scales with a temporal domain: values in the input domain are assumed to be Date objects or timestamps. The time scale type uses the current local timezone setting. UTC scales (utc) instead use Coordinated Universal Time. Both time and utc scales use a default domain of [2000-01-01, 2000-01-02], and a default unit range [0, 1].

Sequential Scales (Deprecated)

Sequential scales (sequential) are similar to linear scales, but use a fixed interpolator to determine the output range. As of Vega 5.0, sequential scales are deprecated: specifications should now use a linear (or log, etc.) scale with a color-valued range, rather than a sequential scale.

Back to scale type reference

Discrete Scales

Discrete scales map values from a discrete domain to a discrete range. In the case of band and point scales, the range is determined by discretizing a continuous numeric range.

Ordinal Scales

Ordinal scales (ordinal) have a discrete domain and range. For example, an ordinal scale might map a set of named categories to a set of colors, or to a set of shapes. Ordinal scales function as a “lookup table” from a domain value to a range value.

This example uses an ordinal scale for color-coded categories, with up to 20 unique colors:

{
  "scales": [
    {
      "name": "color",
      "type": "ordinal",
      "domain": {"data": "table", "field": "category"},
      "range": {"scheme": "category20"}
    }
  ]
}

Band Scales

Band scales (band) accept a discrete domain similar to ordinal scales, but map this domain to a continuous, numeric output range such as pixels. Discrete output values are automatically computed by the scale by dividing the continuous range into uniform bands. Band scales are typically used for bar charts with an ordinal or categorical dimension.

In addition to a standard numerical range value (such as [0, 500]), band scales can be given a fixed step size for each band. The actual range is then determined by both the step size and the cardinality (element count) of the input domain. The step size is specified by an object with a step property that provides the step size in pixels, for example "range": {"step": 20}.

This image from the d3-scale documentation illustrates how a band scale works:

Point Scales

Point scales (point) are a variant of band scales where the internal band width is fixed to zero. Point scales are typically used for scatterplots with an ordinal or categorical dimension. Similar to band scales, point scale range values may be specified using either a numerical extent ([0, 500]) or a step size ({"step": 20}). As point scales do not have internal band widths (only step sizes between bands), they do not accept the paddingInner property.

This image from the d3-scale documentation illustrates how a point scale works:

Back to scale type reference

Discretizing Scales

Discretizing scales break up a continuous domain into discrete segments, and then map values in each segment to a range value.

Quantile Scales

Quantile scales (quantile) map a sample of input domain values to a discrete range based on computed quantile boundaries. The domain is considered continuous and thus the scale will accept any reasonable input value; however, the domain is specified as a discrete set of sample values. The number of values in (i.e., the cardinality of) the output range determines the number of quantiles that will be computed from the domain. To compute the quantiles, the domain is sorted, and treated as a population of discrete values. The resulting quantile boundaries segment the domain into groups with roughly equal numbers of sample points per group.

Quantile scales are particularly useful for creating color or size encodings with a fixed number of output values. Using a discrete set of encoding levels (typically between 5-9 colors or sizes) sometimes supports more accurate perceptual comparison than a continuous range. For related functionality see quantize scales, which partition the domain into uniform domain extents, rather than groups with equal element counts. Quantile scales have the benefit of evenly distributing data points to encoded values. In contrast, quantize scales uniformly segment the input domain and provide no guarantee on how data points will be distributed among the output visual values.

This example color-codes quantile values in five groups, using colors sampled from a continuous color scheme:

{
  "name": "color",
  "scale": "quantile",
  "domain": {"data": "table", "field": "value"},
  "range": {"scheme": "plasma", "count": 5}
}

Quantize Scales

Quantize scales (quantize) 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.

Quantize scales are particularly useful for creating color or size encodings with a fixed number of output values. Using a discrete set of encoding levels (typically between 5-9 colors or sizes) sometimes supports more accurate perceptual comparison than a continuous range. For related functionality see quantile scales, which partition the domain into groups with equal element counts, rather than uniform domain extents.

This example color-codes a quantized domain using a 7-point color scheme:

{
  "name": "color",
  "scale": "quantize",
  "domain": {"data": "table", "field": "value"},
  "range": {"scheme": "blues", "count": 7}
}

Threshold Scales

Threshold scales (threshold) are similar to quantize scales, except they allow mapping of arbitrary subsets of the domain (not uniform segments) to discrete values in the range. The input domain is still continuous, and divided into slices based on a set of threshold values provided to the domain property. The range property must have N+1 elements, where N is the number of threshold boundaries provided in the domain.

Given the following scale definition,

{
  "name": "threshold",
  "type": "threshold",
  "domain": [0, 1],
  "range": ["red", "white", "blue"]
}

the scale will map domain values to color strings as follows:

-1   => "red"
0    => "white"
0.5  => "white"
1.0  => "blue"
1000 => "blue"

Bin-Ordinal Scales

Binned ordinal scales (bin-ordinal) are a special type of ordinal scale for use with data that has been subdivided into bins (for example, using Vega’s bin transform). The main benefit of using bin-ordinal scales is that they provide “bin-aware” routines for sampling values and generating labels for inclusion in legends. They are particularly useful for creating binned color encodings.

The domain values for a binned ordinal scale must be the set of all bin boundaries, from the minimum bin start to maximum bin end. Input domain values are discretized to the appropriate bin, which is then treated as a standard ordinal scale input. However, as the domain property only accepts an array of values, the bin-ordinal scale provides a bins property that also accepts a bin specification and can be used instead of an explicit domain property.

Here is an example of a bin-ordinal scale defined in conjunction with a bin transform:

{
  "data": [
    {
      "name": "input",
      "transform": [
        { "type": "extent", "field": "value", "signal": "extent" },
        { "type": "bin", "extent": {"signal": "extent"}, "signal": "bins" }
      ]
    }
  ],
  "scales": [
    {
      "name": "color",
      "type": "bin-ordinal",
      "bins": {"signal": "bins"},
      "range": {"scheme": "greens"}
    }
  ]
}

Back to scale type reference

Scale Bins

Bin boundaries can be provided to scales as either an explicit array of bin boundaries or as a bin specification object. The legal values are:

• A signal reference that resolves to either an array or bin specification object.
• An array literal of bin boundary values. For example, [0, 5, 10, 15, 20]. The array must include both starting and ending boundaries. The previous example uses five values to indicate a total of four bin intervals: [0-5), [5-10), [10-15), [15-20]. Array literals may include signal references as elements.
• A bin specification object that indicates the bin step size, and optionally the start and stop boundaries. The output value of a bin transform is a valid bin specification object.

Scale Domains

Scale domains can be specified in multiple ways:

• As an array literal of domain values. For example, [0, 500] or ['a', 'b', 'c']. Array literals may include signal references as elements.
• A signal reference that resolves to a domain value array. For example, {"signal": "myDomain"}.
• A data reference object that specifies field values in one or more data sets.

Basic Data Reference

A basic data reference indicates a data set, field name, and optional sorting for discrete scales:

For example, "domain": {"data": "table", "field": "value"}, derives a scale domain from the value field of data objects in the table data set. If the scale type is quantitative or a quantize, the derived domain will be a two-element [min, max] array. If the scale type is discrete, the derived domain will be an array of all distinct values. If the scale type is quantile, all values will be used to compute quantile boundaries.

Multi-Field Data References

Scale domains can also be derived using values from multiple fields. Multiple fields from the same data set can be specified by replacing the field property with a fields property that takes an array of field names:

More generally, scale domains may also use values pulled from different data sets. In this case, the domain object should have a fields property, which is an array of basic data references:

Here is an example that constructs a domain using the fields price and cost drawn from two different data sets:

"domain": {
  "fields": [
    {"data": "table1", "field": "price"},
    {"data": "table2", "field": "cost"}
   ]
}

Sorting Domains

The sort property of a domain data reference can accept, in addition to a simple boolean, an object-valued sort definition:

This example sorts distinct category field values in descending order by the associated median of the value field:

{
  "domain": {
    "data": "table",
    "field": "category",
    "sort": {"op": "median", "field": "value", "order": "descending"}
  }
}

This example sorts a multi-field domain in descending order based on the counts of each of the domain values:

{
  "domain": {
    "data": "table",
    "fields": ["category1", "category2"],
    "sort": {"op": "count", "order": "descending"}
  }
}

Note: For multi-field domains, the sort field values may not be undefined across all input data sets, and will exhibit duplicate values when drawing multiple domain values from the same data set. To avoid inaccurate sorting, the only allowed sort op values for multi-domain scales are count, min, and max. Support for min and max is available in versions ≥ 5.5.

Scale Ranges

Scale ranges can be specified in multiple ways:

• As an array literal of range values. For example, [0, 500] or ['a', 'b', 'c']. Array literals may include signal references as elements.
• A signal reference that resolves to a range value array. For example, {"signal": "myRange"}.
• A color scheme reference for a color palette. For example, {"scheme": "blueorange"}.
• For ordinal scales only, a data reference for a set of distinct field values. For example, {"data": "table", "field": "value"}.
• For band and point scales only, a step size for each range band. For example, {"step": 20}.
• A string indicating a pre-defined scale range default. For example, "width", "symbol", or "diverging".

Scale Range Defaults

Scale ranges can also accept string literals that map to default values. Default values can be modified, and new named defaults can be added, by using custom config settings.