Scale

Scales are functions that transform a domain of data values (numbers, dates, strings, etc.) to a range of visual values (pixels, colors, sizes). Internally, Vega-Lite uses Vega scales, which are derived from the d3-scale library. For more background about scales, please see “Introducing d3-scale” by Mike Bostock.

Vega-Lite automatically creates scales for fields that are mapped to position and mark property channels. To customize the scale of a field, users can provide a scale object as a part of the field definition to customize scale properties (e.g., type, domain, and range).

// Single View Specification
{
  "data": ... ,
  "mark": ... ,
  "encoding": {
    "x": {
      "field": ...,
      "type": ...,
      "scale": {                // scale
        "type": ...,
        ...
      },
      ...
    },
    "y": ...,
    ...
  },
  ...
}

Besides the scale property of each encoding channel, the top-level configuration object (config) also provides scale config (config: {scale: {...}}) for setting default scale properties for all scales.

For more information about guides that visualize the scales, please see the axes and legends pages.

Documentation Overview

• Scale Types
• Scale Domains
• Scale Ranges
  • Color Schemes
• Continuous Scales
  • Linear Scales
  • Power Scales
  • Square Root Scales
  • Logarithmic Scales
  • Time and UTC Scales
  • Sequential Scales
  • Piecewise Scales
• Discrete Scales
  • Ordinal Scales
  • Band and Point Scales
• Discretizing Scales
  • Bin-Linear Scales
  • Bin-Ordinal Scales
• Disabling Scale
• Configuration
  • Scale Config
  • Range Config

Scale Types

The type property can be specified to customize the scale type.

By default, Vega-Lite use the following scale types for the following data types and encoding channels:

¹ Quantitative fields with the bin transform. ² For positional (x and y) ordinal and ordinal fields, "point" is the default scale type for all marks except bar and rect marks, which use "band" scales. ³ For static plots, both "linear" and "bin-linear" work with binned fields on x and y. However, panning and zooming do not work with discretized scales such as "bin-linear", thus we use "linear" as the default scale type for binned fields on x and y.

Scale Domains

By default, a scale in Vega-Lite draws domain values directly from a channel’s encoded field. Users can specify the domain property of a scale to customize its domain values. To sort the order of the domain of the encoded, the sort property of a field definition can be specified.

A common use case for the domain property is to limit, for example, the x range of values to include in a plot. However, setting the domain property alone is insufficient to achieve the desired effect. For example, consider the line plot specification below in which the x domain is restricted to the range [300, 450].

There are two approaches to keep the mark from being plotted outside the desired x range of values.

• The first one is to set clip: true in mark definition.

• The second approach is to use transform. Note that these two approaches have slightly different behaviors. Using transform removes unwanted data points, yet setting clip to true clips the mark to be the enclosing group’s width and height.

Scale Ranges

The range of the scale represents the set of output visual values. Vega-Lite automatically determines the default range for each encoding channel using the following rules:

To customize range values, users can directly specify range, or the special range properties: rangeStep and padding for band and point scales and scheme for ordinal and sequential color scales.

Color Schemes

Color schemes provide a set of named color palettes as a scale range for the color channel. Vega-Lite (via Vega) provides a collection of perceptually-motivated color schemes, many of which are drawn from the d3-scale, d3-scale-chromatic, and ColorBrewer projects.

By default, Vega-Lite assigns different default color schemes based on the types of the encoded fields:

• Nominal fields use the "categorical" pre-defined named range (the "tableau10" scheme by default).

• Ordinal fields use the "ordinal" pre-defined named color range (the "blues" color scheme by default).

• Quantitative and temporal fields use the pre-defined named color range "heatmap" (the "viridis" scheme by default) for rect marks and "ramp" (the "blues" scheme by default) for other marks.

There are multiple ways to customize the scale range for the color encoding channel:

1) Set a custom scheme.

For example, the following plot use the "category20b" scheme.

The scheme property can also be a scheme parameter object, which contain the following properties:

2) Setting the range property to an array of valid CSS color strings.

3) Change the default color schemes using the range config.

Continuous Scales

Continuous scales map a continuous domain (numbers or dates) to a continuous output range (pixel locations, sizes, colors). Supported continuous scale types for quantitative fields are "linear", "log", "pow", "sqrt", and "sequential". Meanwhile, supported continuous scale types for temporal fields are "time", "utc", and "sequential".

By default, Vega-Lite uses "linear" scales for quantitative fields and uses "time" scales for temporal fields for all encoding channels except for color, which uses "sequential" scales for both quantitative and temporal fields.

In addition to type, domain, and range, continuous scales support the following properties:

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.

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.

Logarithmic Scales

Log scales ("log") are quantitative 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_a(x) + b, where a is the logarithmic base.

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.

Example: The following plot has a logarithmic y-scale.

Time and UTC Scales

Time and UTC scales ("time" and "utc") are continuous scales with a temporal domain: values in the input domain are assumed to be Date objects or timestamps. Time scales use the current local timezone setting. UTC scales instead use Coordinated Universal Time.

Sequential Scales

Sequential scales ("sequential") are similar to linear scales, but use a fixed interpolator to determine the output range. By default, Vega-lite uses sequential scales to encode continuous (quantitative and temporal) fields with colors.

To customize the range of a sequential scale, either a range array listing colors or a color scheme can be specified.

Piecewise Scales

We can use any types of continuous scales ("linear", "pow", "sqrt", "log", "time", "utc", "sequential") to create a diverging color graph by specifying a custom domain with multiple elements.

If range is specified, the number of elements in range should match with the number of elements in domain. Diverging color schemes are also useful as a range for a piecewise scale.

Example

Discrete Scales

Discrete scales map values from a discrete domain to a discrete or continuous range.

Ordinal Scales

Ordinal scales ("ordinal") have a discrete domain and range. These scales function as a “lookup table” from a domain value to a range value.

By default, Vega-Lite automatically creates ordinal scales for color and shape channels. For example, the following plot implicitly has two ordinal scales, which map the values of the field "Origin" to a set of colors and a set of shapes.

The range of an ordinal scale can be an array of desired output values, which are directly mapped to elements in the domain. Both domain and range array can be re-ordered to specify the order and mapping between the domain and the output range. For ordinal color scales, a custom scheme can be set as well.

Band and Point Scales

Band and point scales accept a discrete domain similar to ordinal scales, but map this domain to a continuous, numeric output range such as pixels.

Band scales ("band") compute the discrete output values 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.

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

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}).

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

By default, Vega-Lite uses band scales for nominal and ordinal fields on position channels (x and y) of bar or rect marks. For x and y of other marks and size and opacity, Vega-Lite uses point scales by default.

For example, the following bar chart has uses a band scale for its x-position.

To customize the range of band and point scales, users can provide the following properties:

For example, we can set the rangeStep property to make the bands of the bars smaller.

Discretizing Scales

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

Bin-Linear Scales

Binned linear scales ("bin-linear") are a special type of linear scale for use with binned fields to correctly create legend labels. Vega-Lite always uses binned linear scales with binned quantitative fields on size and opacity channels.

For example, the following plot has a binned field on the size channel.

Bin-Ordinal Scales

Binned ordinal scales ("bin-ordinal") are a special type of ordinal scale for use with binned fields to correctly create legend labels. Vega-Lite always uses binned ordinal scales with binned quantitative fields on the color channel.

For example, the following plot has a binned field on the color channel.

Similar to ordinal color scales, a custom range or scheme can be specified for binned ordinal scales.

Disabling Scale

To directly encode the data value, the scale property can be set to null.

For example, the follow bar chart directly encodes color names in the data.

Configuration

// Top-level View Specification
{
  ...
  "config": {
    "scale": {
      ...                       // Scale Config
    },
    "range": {
      ...                       // Scale Range Config
    },
    ...
  }
  ...
}

Scale Config

To provide themes for all scales, the scale config (config: {scale: {...}}) can contain the following properties:

Range Config

The scale range configuration (config: {range: {...}}) defines key-value mapping for named scale ranges: the keys represent the range names, while the values define valid range or, for named color ranges, Vega scheme definitions.

By default, Vega-Lite (via Vega) includes the following pre-defined named ranges:

See this file for the default values of named ranges.