Debugging Guide

A collection of methods for debugging Vega visualizations at runtime. All examples below assume that the Vega View instance to debug has been bound to the view variable. To access the view in the online editor, open the debug console and use VEGA_DEBUG.view.

Debugging Methods

Inspect Signal Values

To inspect signal values, use the view.signal method:

view.signal('name') // returns the value of the signal 'name'

You can also use the same method to set signals due to a desired value. You will still need to invoke view.run() to re-run the dataflow after updating any values.

view.signal('name', value).run(); // update signal 'name' and run the dataflow

The view.signal method will only return signals defined in the top-level of a Vega specification. To view signals defined in nested group marks, create a state snapshot or inspect the runtime scope.

Inspect Data Sets

To inspect a data set, use the view.data method:

view.data('name') // return a data object array for the data set 'name'

The view.data method returns the output of any data transforms applied. To get access to both input and output data, read about inspecting runtime scope below. Also, this method will only return data sets defined in the top-level of a Vega specification. To view data sets defined in nested group marks, create a state snapshot or inspect the runtime scope.

Snapshot Signal and Data State

The view.getState method returns a snapshot of active signals and data sets, and may be a convenient way to inspect the state of a visualization. The view.setState method can then be used to restore the state back to a previous value, which may sometimes be useful for testing.

view.getState() // {signals: [...], data: [...], subcontext: [...]}

The view.getState method returns an object whose properties are a hash of all named signals and a hash of all named input data sets. The getState method returns data sets prior to applying transforms, as this is more appropriate for changing the visualization back to a previous state. In addition, if a visualization includes nested group marks with signal or data set definitions, a subcontext property is included which contains state information for all nested scopes.

Inspect the Scenegraph

It is often helpful to be able to inspect the visual values on scenegraph items, as well as associated data objects. To access the scenegraph from the console, use the view.scenegraph method and access the scenegraph items starting with the root property. Each mark group and scenegraph items can then be accessed under the items property.

var root = view.scenegraph().root; // {marktype: "group", items: [...], ...}

It can sometimes be tedious to walk down the scenegraph tree manually. Scenegraph items can be accessed in a more direct manipulation way when using the SVG renderer. For example, if using the Chrome browser, first right click an element and select “Inspect” from the menu. The resulting SVG element will be bound to the global variable $0. The Vega scenegraph item is then accessible in the console as $0.__data__, and the backing data object is $0.__data__.datum.

Debugging Expressions

Debugging messages can be added to expressions using the logging methods: warn, info, debug. The last argument provided to these functions is used as the return value; this allows logging methods to be added to existing expressions without changing the logic of a specification.

To ensure that log messages make their way to the console, the Vega view must have the correct logging level set. For example, to ensure that warning messages are printed to the console:

view.logLevel(vega.Warn);

Inspect the Runtime Scope

If the above methods prove insufficient, one can also get down and dirty by directly inspecting the internals of the Vega dataflow graph. The dataflow graph consists of a set of operators (or nodes) that compute values and/or process streams of data objects. Operators are connected in a dependency graph structure, and each has a value property indicating the computed value for that node.

To access dataflow operators for the top-level scope, using the view._runtime property. Note that this is not an “official” part of the Vega API, but nonetheless can useful for advanced debugging. Do not modify any properties within the runtime object. If modified, the subsequent visualization behavior is undefined.

view._runtime // {signals: {}, data: {}, scales: {}, nodes: {}, subcontext: [], ...}

The runtime scope object includes properties for:

  • signals - Dataflow operators corresponding to each named signal.
  • data - Holds input, output and values nodes for each named data set. Inspect the input node for pre-transform data objects; inspect the values node for post-transform data objects.
  • scales - Dataflow operators corresponding to named scales and projections.
  • nodes - An id-based lookup table of all dataflow operators in the current scope (including transforms).
  • subcontext - An array of recursive runtime scopes for nested group marks.