This tutorial introduces the basics of Vega. We’ll look at a bar chart with tooltips and deconstruct it into its component elements. After completing the tutorial, you should be ready to start exploring and modifying Vega visualizations.
Here is one of the most basic (but also most useful!) forms of visualization, the humble bar chart:
Here is the Vega specification that defines this bar chart. First read through the full definition. We’ll then examine each part in turn.
{"$schema":"https://vega.github.io/schema/vega/v6.json","width":400,"height":200,"padding":5,"data":[{"name":"table","values":[{"category":"A","amount":28},{"category":"B","amount":55},{"category":"C","amount":43},{"category":"D","amount":91},{"category":"E","amount":81},{"category":"F","amount":53},{"category":"G","amount":19},{"category":"H","amount":87}]}],"signals":[{"name":"tooltip","value":{},"on":[{"events":"rect:mouseover","update":"datum"},{"events":"rect:mouseout","update":"{}"}]}],"scales":[{"name":"xscale","type":"band","domain":{"data":"table","field":"category"},"range":"width","padding":0.05,"round":true},{"name":"yscale","domain":{"data":"table","field":"amount"},"nice":true,"range":"height"}],"axes":[{"orient":"bottom","scale":"xscale"},{"orient":"left","scale":"yscale"}],"marks":[{"type":"rect","from":{"data":"table"},"encode":{"enter":{"x":{"scale":"xscale","field":"category"},"width":{"scale":"xscale","band":1},"y":{"scale":"yscale","field":"amount"},"y2":{"scale":"yscale","value":0}},"update":{"fill":{"value":"steelblue"}},"hover":{"fill":{"value":"red"}}}},{"type":"text","encode":{"enter":{"align":{"value":"center"},"baseline":{"value":"bottom"},"fill":{"value":"#333"}},"update":{"x":{"scale":"xscale","signal":"tooltip.category","band":0.5},"y":{"scale":"yscale","signal":"tooltip.amount","offset":-2},"text":{"signal":"tooltip.amount"},"fillOpacity":[{"test":"isNaN(tooltip.amount)","value":0},{"value":1}]}}}]}We’ll now walk through the visualization definition visiting each of these components:
The first set of top-level properties determine the size of the visualization:
"width":400,"height":200,"padding":5,"autosize":"pad",Thewidth andheight values determine the size of thedata rectangle: the area of the chart in which data is plotted. Additional components, such as axes and legends, may take up additional space.
Thepadding determines the margin between the chart content and the border of the view.
Theautosize property determines how the final chart size is determined:
"pad" (the default) introduces extra space to accommodate all visualized marks, including axes and legends. The data rectangle size is unchanged. If any marks are placed at extreme positions outside the data rectangle, the view component may become very large!"fit" tries to fit the entire chart (data rectangle, axes, legends, butnot padding) within the providedwidth andheight. Vega will shrink the data rectangle to accommodate axes and legends. In some cases clipping may occur, for instance if a legend is very tall."none" disables automatic sizing. The total chart size is determined solely by thewidth andheight pluspadding. There are no modifications to accommodate axes, legends, etc.For more details, see thetop-level specification documentation.
Thedata property is an array of data definitions. Each entry in the data array must be an object with a uniquename for the data set. As shown here, data can be directly defined inline using thevalues property. In this example, we have an array of data objects with fields namedcategory (a string label) andamount (a number).
"data":[{"name":"table","values":[{"category":"A","amount":28},{"category":"B","amount":55},{"category":"C","amount":43},{"category":"D","amount":91},{"category":"E","amount":81},{"category":"F","amount":53},{"category":"G","amount":19},{"category":"H","amount":87}]}],In Vega specifications, data can be:
url property (including JSON and CSV files),source property, orOnlyone of thevalues,url orsource properties may be defined.
Data sets in Vega can be modified using a collection oftransforms such as filtering, aggregation and layout operations. Transformations are specified using thetransform property, which takes an array of transform definitions.
For more details, see thedata andtransform documentation.
Scale functions map data values to visual values, such as pixel positions or colors:
"scales":[{"name":"xscale","type":"band","domain":{"data":"table","field":"category"},"range":"width","padding":0.05,"round":true},{"name":"yscale","domain":{"data":"table","field":"amount"},"nice":true,"range":"height"}],Here we’ve defined two scales, one each for the X and Y axes. The X-axis uses an ordinalband scale, which maps adomain of ordered elements (in this case letters) to a visualrange. The Y-axis uses a quantitativelinear scale. A linear scale type is used by default, and so is not explicitly included in theyscale definition above.
Each scale definition should have aunique name. Though to be precise, scale definitions nested withingroup markscan repeat names to override previously defined scales – but that is a more advanced concept.
Therange settings of"width" and"height" are conveniences provided by Vega, and in this case map to the arrays[0, 400] and[200, 0], as defined by the size of the visualization. Ranges can also be defined explicitly as arrays of values: two-element numerical arrays should be used for spatial mappings, longer arrays (e.g., of RGB hex values like"#ffa804") can be used as the range ofordinal scales to specify custom palettes.
Thedomain property determines the input domain for the scale. The domain can be defined directly as an array of values (a quantitative range or list of ordinal values) or determined dynamically from the data. In the example above, the domain consists of the minimum and maximum values of theamount field in thetable data set. By default, quantitative scales automatically include the zero value. To disable this feature, include the property"zero": false in the scale definition.
Thexscale definition also includes a fractionalpadding to add spacing between bars and around parameter to make sure the bars snap to pixel boundaries. Notice thatyscale includes the property"nice": true. This optional property tells Vega that the scale domain can be made “nice” so that it is more human-friendly and readable. For example, if the raw data domain is[0, 94.345] it is made “nicer” as[0, 100].
For more details, see thescales documentation.
Axes visualize scales using ticks and labels to help viewers interpret a chart.
"axes":[{"orient":"bottom","scale":"xscale"},{"orient":"left","scale":"yscale"}],At minimum, an axis definition must specify the axis orientation and the scale to visualize. Here we add an X-axis at thebottom of the chart, and a Y-axis to theleft of the chart.
Now let’s look at how we might further customize the axes:
"axes":[{"orient":"bottom","scale":"xscale"},{"orient":"right","scale":"yscale","tickCount":5,"offset":6}],Here we’ve adjusted the Y-axis in multiple ways, resulting in the modified chart below. By setting"tickCount": 5, we’ve requested that the axis show roughly five tick marks, rather than the ten or so shown previously. By setting"orient": "right", we’ve requested that the axis be placed on the right side of the chart, rather than the previous left position. Finally, setting"offset": 6 adjusts the axis position, in this case moving it to the right by 6 pixels. Here’s the modified visualization:
For more details, see theaxes documentation.
Marks are the primary elements of a visualization: they are graphical primitives whose properties (such as position, size, shape, and color) can be used to visually encode data. Vega provides a set of marks that serve as building blocks that can be combined to form rich visualizations. Here, we simply use rectangles (rect marks) to construct a bar chart.
Every mark must have atype property, which determines which kind of mark (rect,area,line,symbol, etc.) to use. Next, we must specify the data to be visualized using thefrom property. In most cases, one simply needs to reference a named data set defined in the top-leveldata property. If nofrom property is provided, a single mark instance will be created.
"marks":[{"type":"rect","from":{"data":"table"},"encode":{"enter":{"x":{"scale":"xscale","field":"category"},"width":{"scale":"xscale","band":1},"y":{"scale":"yscale","field":"amount"},"y2":{"scale":"yscale","value":0}},"update":{"fill":{"value":"steelblue"}},"hover":{"fill":{"value":"red"}}}},Visual mark properties, such as position and color, are specified using namedencoding sets defined within theencode property. The standard encoding sets are theenter set (for properties that should be set when the mark is first created), theexit set (for property settings when a mark is about to be removed), theupdate set (to update settings upon changes), and thehover set (to set properties upon mouse hover). In the example above, theenter set is first evaluated, followed by theupdate set, to create the bar chart. Upon mouse over, thehover set is evaluated to color the hovered bar in red. When the mouse leaves a bar, theupdate set is evaluated again to return the bar to its original color. Note that if we omit theupdate set, a mouse hover would cause the bar to turn permanently red!
Now let’s take a closer look at the specific mark definitions in theenter set:
"x":{"scale":"xscale","field":"category"},"width":{"scale":"xscale","band":1},"y":{"scale":"yscale","field":"amount"},"y2":{"scale":"yscale","value":0}The first two properties (x andwidth) set the horizontal position and width of the bar. Thex mark property (the leftmost edge of the bar) is set to the value obtained by applying the scale named"xscale" (defined inscales above) to the data fieldcategory.
Thewidth property is set to a value provided by the band scalexscale. Band scales chop up a spatial range into a set of uniformly sized “bands”. Including"band": 1 retrieves the full size of the band for the scale. The1 value indicates what fraction of the band size to include; using"band": 0.5 would use half of the band.
The second two properties (y andy2) determine the vertical position and height of the bars. Similar tox andwidth, onecould usey andheight properties. However, here it is easier to specify the bar heights using two end points: one for the top of the bar (y) and one for the bottom of the bar (y2). We hardwire the value0 and pass it through the linearyscale to ensure that one edge of each bar is always at zero. It actually does not matter which ofy ory2 is greater than the other; Vega will set the positions correctly. You can similarly usex andx2, which can be useful for creating visualizations such as horizontal bar charts and timelines.
In addition to standard graphical marks (rectangles, arcs, plotting symbols, etc), Vega also supports nested marks through the specialgroup mark type. Groups are marks that can contain other marks, for example to createsmall multiple displays. Groups can also include customscales andaxes definitions that are specific to a group instance.
For more details, see themarks documentation.
Signals act as dynamic variables: expressions that are automatically reevaluated when other signal values change, or when input events occur. Each signal must have a uniquename and an initialvalue; other properties define how the signal value can change.
Here we use a signal to define a tooltip interaction. In this example, the value of thetooltip signal changes in response tomouseover andmouseout events onrect marks. Every time these events occur, the corresponding expression is evaluated and set as thetooltip value. Thus, when the mouse pointer is moved over a rectangle mark,tooltip is equal to the mark’s backing datum; when the pointer is moved off the rectangle,tooltip is an empty object.
"signals":[{"name":"tooltip","value":{},"on":[{"events":"rect:mouseover","update":"datum"},{"events":"rect:mouseout","update":"{}"}]}],Ourtooltip signal tracks the datum for the currently highlighted bar. We now use this signal to dynamically adjust the visual encoding rules of a text label:
{"marks":[...,{"type":"text","encode":{"enter":{"align":{"value":"center"},"baseline":{"value":"bottom"},"fill":{"value":"#333"}},"update":{"x":{"scale":"xscale","signal":"tooltip.category","band":0.5},"y":{"scale":"yscale","signal":"tooltip.amount","offset":-2},"text":{"signal":"tooltip.amount"},"fillOpacity":[{"test":"isNaN(tooltip.amount)","value":0},{"value":1}]}}}]A single text mark instance serves as our tooltip text (note that thefrom property is omitted). The position and text values are drawn directly from thetooltip signal. To only show the tooltip text when the mouse pointer is over a rectangle, we set thefillOpacity usingproduction rules: a chain of if-then-else rules for visual encoding. Iftooltip is an empty object, the tooltip text is fully transparent sinceisNaN(tooltip.amount) istrue, otherwise it is opaque.
Signals can be applied throughout a specification. For example, they can be used to specify the properties oftransforms,scales andmark encodings. For more details, see thesignals documentation.
We’ve now worked through a full Vega visualization! Next, we recommend experimenting with and modifying this example. Copy & paste the full specification above into the onlineVega Editor or forkour example Block.
You should then be ready to understand and modify other examples. Many of the more advanced examples include data transforms that organize data elements and perform layout. As you experiment with different examples, you may find it useful to refer to the documentation for each of the main specification components.