Scale

Scales are functions that transform a domain of data values (numbers, dates, strings, etc) to a range of visual values (pixels, colors, sizes).

Vega-Lite automatically creates scales for fields that are mapped to mark properties. Supported scale types are quantitative, time, and ordinal. Default scale properties are determined based on a set of rules for each scale type, but scale property of the channel definition can be provided to customize the scale’s properties.

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

The rest of this page describes properties of a scale and their default behavior.

• Scale Type
  • Example: Log Scale
• Scale Domain
• Scale Range
  • Built-in Color Palettes
  • Example: Default Color Ranges based on Data Types
  • Example: Custom Color Range
  • Piecewise Scale Example: Diverging Color Scale
• Other Scale Properties
  • General Scale Properties
  • Quantitative Scale Properties
  • Time Scale Properties
  • Ordinal Scale Properties
    • Example: Custom Band Width

Scale Type

Vega-Lite supports the following scale types:

Quantitative Scale

A quantitative scales takes continuous, quantitative data as its input domain. There are multiple types of quantitative scales. linear, power, and log scales output continuous ranges. Meanwhile quantize and quantile scales output discrete ranges.

• linear scale expresses each range value y as a linear function of the domain value x: y = mx + b. This is the default scale for a quantitative field (field with type = "quantitative").
• pow scale expresses each range value y as a power (exponential) function of the domain value x: y = mx^k + b, where k is the exponent value. (k can be customized using exponent property.)
• log scale expresses each range value y as a logarithmic function of the domain value x: y = mlog(x) + b. As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero. Vega-Lite automatically filters zero values from the field mapped to a log scale.
• quantize scale maps continuous value to a discrete range by dividing the domain 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.
• quantile scale maps a sampled input domain to a discrete range by sorting the domain and compute the quantiles. The cardinality of the output range determines the number of quantiles that will be computed.

Time Scale

A time scale is similar to a linear quantitative scale but takes date as input. In general, a temporal field has time scale by default. The exceptions are temporal fields with hours, day, date, month as time unit; they have ordinal scales by default.

Ordinal Scale

An ordinal scale (ordinal) takes discrete domain as their input domain. Ordinal (ordered) and nominal (unordered/categorical) data always use ordinal scale.

• An ordinal color scale with nominal data outputs categorical color palette while an ordinal color scale with ordinal data outputs sequential color ramp. (See example.)
• An ordinal shape scale always produces a categorical range since shape cannot convey order.
• Ordinal scales for other channels (x, y, size) always output sequential range. The default order for nominal data is determined by Javascript’s natural order. For example, "a" < "b".

Note: For more information about scale types, please see d3 scale documentation.

Example: Log Scale

The following example has a logarithmic y-scale.

Scale Domain

By default, a scale draws domain values directly from the channel field. Custom domain values can be specified via the scale’s domain property.

Note: To sort the order mapping between the domain values and range, please use the channel definition’s sort property.

Scale Range

The range of the scale represents the set of output visual values. Vega-Lite automatically determines appropriate range based on the scale’s channel and type, but range property can be provided to customize range values.

x and y Scales

For continuous x and y scales (quantitative and time), the range are always [0, cellWidth] and [0, cellHeight] (See config.cell for customizing cell width and height). For ordinal x and y scales, the maximum range is a product of the field’s cardinality and bandSize. Not Customizable: specified range will be ignored.

Nominal color Scales

A color scale of a nominal field has a categorical color palette as its range. Customized categorical color range can be either a string literal for a palette name or an array of desired output values. Default value: derived from scale config’s nominalColorRange ("category10" by default).

Sequential color Scales

A color scale for ordinal, temporal, and quantitative fields have a sequential color ramp as its range. Currently, Vega-Lite only supports color ramp that interpolate between two color values. Customized sequential color range takes a two-element array of color values for interpolation. Default value: derived from scale config’s sequentialColorRange (green ramp between ["#AFC6A3", "#09622A"] by default).

shape Scales

A shape scale has a list of shape type names as its range. A customized shape range is an array of supported shapes. Default value: derived from scale config’s shapeRange This is, by default, the "shape" palette, which is equivalent to["circle", "cross", "diamond", "square", "triangle-down", "triangle-up"].

size Scales

A size scale has a sequential range. Customized size range can be either a two-element array of size values for the interpolation or (for ordinal size scale only) an array of desired output size for each domain value. Default value:
• for bar: derived from scale config’s barSizeRange. If both scale’s range and the scale config’s barSizeRange are unspecified (default), the default size range is a range from mark config’s thinBarWidth to the scale’s bandSize.
• for point, square, and circle: derived from scale config’s pointSizeRange. If both scale’s range and the scale config’s pointSizeRange are unspecified (default), the default size range is a range from 9 to the square of the scale’s bandSize (bandSize^2).
• for text: derived from scale config’s fontSizeRange ([8, 40] by default).
• for tick: derived from scale config’s tickSizeRange ([1, 20] by default).

Built-in Color Palettes

The following built-in palettes can be used as a customized categorical color range value.

Name	Description
"category10"	Set the scale range to a 10-color categorical palette: #1f77b4 #ff7f0e #2ca02c #d62728 #9467bd #8c564b #e377c2 #7f7f7f #bcbd22 #17becf
"category20"	Set the scale range to a 20-color categorical palette: #1f77b4 #aec7e8 #ff7f0e #ffbb78 #2ca02c #98df8a #d62728 #ff9896 #9467bd #c5b0d5 #8c564b #c49c94 #e377c2 #f7b6d2 #7f7f7f #c7c7c7 #bcbd22 #dbdb8d #17becf #9edae5
"category20b"	Set the scale range to a 20-color categorical palette: #393b79 #5254a3 #6b6ecf #9c9ede #637939 #8ca252 #b5cf6b #cedb9c #8c6d31 #bd9e39 #e7ba52 #e7cb94 #843c39 #ad494a #d6616b #e7969c #7b4173 #a55194 #ce6dbd #de9ed6
"category20c"	Set the scale range to a 20-color categorical palette: #3182bd #6baed6 #9ecae1 #c6dbef #e6550d #fd8d3c #fdae6b #fdd0a2 #31a354 #74c476 #a1d99b #c7e9c0 #756bb1 #9e9ac8 #bcbddc #dadaeb #636363 #969696 #bdbdbd #d9d9d9

Example: Default Color Ranges based on Data Types

A color scale of a nominal field outputs a categorical color palette.

Meanwhile, a color scale an ordinal field and a quantitative field outputs a sequential color ramp.

Example: Custom Color Range

We can customize the color range of the scatterplot above by providing scale’s range property. For a nominal color field, range can be an array describing the desired palette.

For ordinal, quantitative, and time fields, range can be a two-element array describing the two colors for interpolation.

Piecewise Scale Example: Diverging Color Scale

We can also create diverging color graph by specify range with multiple elements. Number of elements of range should match with the number of elements in domain. Though continuous scale normally contains 2 elements in both domain and range, having 3 or more elements will create a piecewise scale. For more detail about a piecewise scale, please refer to D3 documentation.

Other Scale Properties

General Scale Properties

Quantitative Scale Properties

Time Scale Properties

Ordinal Scale Properties

Example: Custom Band Width

Given a bar chart:

We can make the band for each bar smaller by providing scale’s bandSize.

For more information about adjusting size of a visualization, please see this page.