Scales

Jeffrey Heer edited this page Mar 7, 2017 · 33 revisions

This wiki documents Vega version 2. For Vega 3 documentation, see vega.github.io/vega.

WikiDocumentationScales

Scales are functions that transform a domain of data values (numbers, dates, strings, etc) to a range of visual values (pixels, colors, sizes). A scale function takes a single data value as input and returns a visual value. Vega includes different types of scales for quantitative data or ordinal/categorical data.

Common Scale Properties

Property Type Description
name String A unique name for the scale.
type String The type of scale. If unspecified, the default value is linear. For ordinal scales, the value should be ordinal. For dates and times the value should be time or utc (for UTC time). The supported quantitative scale types are linear, log, pow, sqrt, quantile, quantize, and threshold. See d3 scale documentation for more information.
domain Array | DataRef The domain of the scale, representing the set of data values. For quantitative data, this can take the form of a two-element array with minimum and maximum values. For ordinal/categorical data, this may be an array of valid input values. The domain may also be specified by a reference to a data source.
domainMin Number | DataRef For quantitative scales only, sets the minimum value in the scale domain. domainMin can be used to override, or (with domainMax) used in lieu of, the domain property.
domainMax Number | DataRef For quantitative scales only, sets the maximum value in the scale domain. domainMax can be used to override, or (with domainMin) used in lieu of, the domain property.
range Array | String | DataRef The range of the scale, representing the set of visual values. For numeric values, the range can take the form of a two-element array with minimum and maximum values. For ordinal or quantized data, the range may be an array of desired output values, which are mapped to elements in the specified domain. See the section on range literals below for more options. For ordinal scales only, the range can be defined using a DataRef: the range values are then drawn dynamically from a backing data set.
rangeMin * Sets the minimum value in the scale range. rangeMin can be used to override, or (with rangeMax) used in lieu of, the range property.
rangeMax * Sets the maximum value in the scale range. rangeMax can be used to override, or (with rangeMin) used in lieu of, the range property.
reverse Boolean If true, flips the scale range.
round Boolean If true, rounds numeric output values to integers. This can be helpful for snapping to the pixel grid.

Ordinal Scale Properties

Property Type Description
points Boolean If true, distributes the ordinal values over a quantitative range at uniformly spaced points. The spacing of the points can be adjusted using the padding property. If false, the ordinal scale will construct evenly-spaced bands, rather than points.
padding Number Applies spacing among ordinal elements in the scale range. The actual effect depends on how the scale is configured. If the points parameter is true, the padding value is interpreted as a multiple of the spacing between points. A reasonable value is 1.0, such that the first and last point will be offset from the minimum and maximum value by half the distance between points. Otherwise, padding is typically in the range [0, 1] and corresponds to the fraction of space in the range interval to allocate to padding. A value of 0.5 means that the range band width will be equal to the padding width. For more, see the D3 ordinal scale documentation.

Time Scale Properties

Property Type Description
clamp Boolean If true, values that exceed the data domain are clamped to either the minimum or maximum range value.
nice String If specified, modifies the scale domain to use a more human-friendly value range. For time and utc scale types only, the nice value should be a string indicating the desired time interval; legal values are "second", "minute", "hour", "day", "week", "month", or "year".

Quantitative Scale Properties

Property Type Description
clamp Boolean If true, values that exceed the data domain are clamped to either the minimum or maximum range value. (Only for linear, log, pow, sqrt.)
exponent Number Sets the exponent of the scale transformation. For pow scale types only, otherwise ignored.
nice Boolean If true, modifies the scale domain to use a more human-friendly number range (e.g., 7 instead of 6.96). (Only for linear, log, pow, sqrt.)
zero Boolean If true, ensures that a zero baseline value is included in the scale domain. This option is ignored for non-quantitative scales. If unspecified, zero is true by default.

Scale Domains

Scale domains may be defined directly as an array of values, or can be inferred from input data. In the latter case, the scale domain can be defined in Vega as an object we call a "DataRef" (for data reference). In most cases, a DataRef is simply an object with up to two properties:

Property Type Description
data String The name of the data set containing domain values.
field Field | Array<Field> | Object | Array<Object> A reference to the desired data field(s) (e.g., "price"). An array of fields will include values for all referenced fields. Typically string values are used to indicate the field to lookup. However, you can specify an indirect lookup of the field name using an object parameter of the form {"parent": "f"}. In this case, the value of the field f is first retrieved from the enclosing group's datum, and then used as the field name for the current data set. In other words, you can determine the field name dynamically from your data.

Advanced Use: For scales that are defined within a group mark, you can omit the data property to tell Vega to instead use the data values that are bound to the group mark instance.

Sorting Domains for Ordinal and Quantile Scales

The domains of ordinal and quantile scales can be sorted by specifying the following additional properties:

Property Type Description
sort Boolean | Object If true, the domain values are sorted in their natural order. If set to an object, the values in the scale domain will be sorted based on an aggregate calculation over a specified sort field.
sort.field Field The field name to aggregate over.
sort.op String A valid aggregation operation (e.g., mean, median, etc.).

Scale Domains drawn from Multiple Fields or Data Sets

To compute a scale domain over multiple data properties, you would typically use an array of field references. However, sometimes you may need to compute the domain over multiple fields from different data sets. For this case, there is a special form of DataRef: an object with a single property ( fields ) that contains an array of DataRef instances.

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"}
   ]
}

For sorted ordinal scales: Each fields object may contain an additional sort property to specify different sort fields for each data set. When set, this property will be used instead of the sort.field property in the ordinal scale definition.

Scale Range Literals

The following string values can be used to automatically set a scale range.

Name Description
width Set the scale range to [0, width], where the width value is defined by the enclosing group or data rectangle.
height Set the scale range to [0, height], where the height value is defined by the enclosing group or data rectangle.
shapes Set the scale range to the symbol type names: ["circle", "cross", "diamond", "square", "triangle-down", "triangle-up"]
category10 Set the scale range to a 10-color categorical palette:

1f77b4 #1f77b4
ff7f0e #ff7f0e
2ca02c #2ca02c
d62728 #d62728
9467bd #9467bd
8c564b #8c564b
e377c2 #e377c2
7f7f7f #7f7f7f
bcbd22 #bcbd22
17becf #17becf
category20 Set the scale range to a 20-color categorical palette:

1f77b4 #1f77b4
aec7e8 #aec7e8
ff7f0e #ff7f0e
ffbb78 #ffbb78
2ca02c #2ca02c
98df8a #98df8a
d62728 #d62728
ff9896 #ff9896
9467bd #9467bd
c5b0d5 #c5b0d5
8c564b #8c564b
c49c94 #c49c94
e377c2 #e377c2
f7b6d2 #f7b6d2
7f7f7f #7f7f7f
c7c7c7 #c7c7c7
bcbd22 #bcbd22
dbdb8d #dbdb8d
17becf #17becf
9edae5 #9edae5
category20b Set the scale range to a 20-color categorical palette:

393b79 #393b79
5254a3 #5254a3
6b6ecf #6b6ecf
9c9ede #9c9ede
637939 #637939
8ca252 #8ca252
b5cf6b #b5cf6b
cedb9c #cedb9c
8c6d31 #8c6d31
bd9e39 #bd9e39
e7ba52 #e7ba52
e7cb94 #e7cb94
843c39 #843c39
ad494a #ad494a
d6616b #d6616b
e7969c #e7969c
7b4173 #7b4173
a55194 #a55194
ce6dbd #ce6dbd
de9ed6 #de9ed6
category20c Set the scale range to a 20-color categorical palette:

3182bd #3182bd
6baed6 #6baed6
9ecae1 #9ecae1
c6dbef #c6dbef
e6550d #e6550d
fd8d3c #fd8d3c
fdae6b #fdae6b
fdd0a2 #fdd0a2
31a354 #31a354
74c476 #74c476
a1d99b #a1d99b
c7e9c0 #c7e9c0
756bb1 #756bb1
9e9ac8 #9e9ac8
bcbddc #bcbddc
dadaeb #dadaeb
636363 #636363
969696 #969696
bdbdbd #bdbdbd
d9d9d9 #d9d9d9