Documentation - smclements/vega GitHub Wiki

Wiki ▸ Documentation

Vega is a visualization grammar: a declarative format for describing and creating data visualizations. Other, existing grammars (Wilkinson's Grammar of Graphics, Wickham's ggplot2 and Tableau's VizQL) focus on rapid generation of charts to support analysis. However, in service of rapid specification these systems make a number of decisions on behalf of the user, and also impose limits on the type of visualizations one can create. Vega is intended to be lower-level, enabling fine-gained control of the visualization design. Vega's model of visualization design is intimately influenced by the Protovis and D3 frameworks, and research at Stanford and the University of Washington.

A Vega specification is simply a JSON object that describes an interactive visualization. A specification describes the data sets used, scale transforms and encoding algorithms, axes and legends, visual marks (rectangles, lines, shapes, etc) whose properties may depend on the data, and signals and predicates that modify the visualization in response to user interaction. In effect, Vega specifications can serve as a "file format" for custom visualization designs. These specifications may be read and interpreted by a runtime system to dynamically create visualizations, or a specification may be cross-compiled to provide a reusable visualization component, in the form of editable code for a specific visualization framework (such as D3).

While intended to be a general (platform-agnostic) specification, Vega has been primary designed for creating web-based visualizations using HTML5 technologies such as Canvas and SVG (Scalable Vector Graphics). This focus has inevitably sculpted the specification language to the web domain.

Overview

A Vega specification is simply a JSON object that describes an interactive visualization design. We will refer to the top-level object as the Visualization specification. A Visualization consists of basic properties (such as the width and height of the view) and definitions for: the Data to visualize, Scales that map data values to visual values, Axes and Legends that visualize these scales, graphical Marks (such as rectangles, circles, arcs, etc) that visualize the data, Signals to capture user interaction and Predicates to modify the visualization in response.

To start learning Vega, we recommend first working through the introductory Bar Chart Tutorial.

Next, you can explore the online examples in the Vega Editor and read the more detailed documentation below.

Specification Components

Documentation for each major component of a Vega specification can be found on these wiki pages:

Page	Description
Visualization	Top-level visualization properties.
Data	Define and load data to visualize.
Data Transforms	Transform data prior to visualization.
Scales	Map data properties to visual properties using scales.
Axes	Axes visualize scales for spatial encodings.
Legends	Legends visualize scales for color, shape and size encodings.
Marks	Visualize data using various graphical marks.
Group Marks	A special kind of mark that can contain other marks.
Signals	Dynamic variables to drive interactive behaviors.
Predicates	Conditions (or "selections") to modify mark properties.
Runtime	Deploying and using the browser-based Vega runtime.
Headless Mode	Server-side Vega using "headless" rendering.