Vega Chart

The Vega Chart widget is used to create fully customizable and interactive visualizations in Workshop using the Vega-Lite grammar. Review the Vega-Lite ↗ documentation for inspiration and examples.

What is Vega?

Vega allows you to create, save, and share interactive visualization designs in the form of a concise JSON spec that describes the appearance and behavior of the visualization. Vega is a higher-level visualization specification language built on top of D3 ↗, and Vega-Lite is a higher-level language built on top of Vega that provides a more concise and convenient way to author common visualizations. The Workshop Vega Chart widget natively supports Vega-Lite, but can render Vega as well.

The Vega Chart widget offers more customizability than the standard XY Chart widget, with support for visualizations such as those below, provided by the official Vega-Lite Example Gallery ↗.

Data Input

Vega data ↗ is a simple array of structs, and in Vega-Lite you can specify multiple datasets:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
"datasets": {
  "nba-player-data": [
    { "name": "Michael Jordan", "height-in-inches": 78, "weight-in-lbs": 216, ... },
    { "name": "Stephen Curry", "height-in-inches": 74, "weight-in-lbs": 185, ... },
    ...
  ],
  "nba-team-data": [
    { "name": "Toronto Raptors", "has-won-championship": true, ... },
    { "name": "Memphis Grizzlies", "has-won-championship": false, ... },
    ...
  ],
}

Data configuration options

The Vega Chart widget has three different configuration options which allow you to flexibly transform object data from your ontology into the expected Vega format:

• Object set: Specify the object set and properties of that object that should be included in the data.

  

• Aggregation: Specify the object set, group by properties with bucketing strategy, and aggregation. Each data point will contain the value of each group by property, as well as the aggregation value keyed by the specified aggregation name.

  

• Function: Specify a function that returns a list of structs that will be directly used as the data.

  

You can have multiple data inputs that can be referenced in the Vega spec by their configured names. Note than you can also inline data into the Vega spec.

Vega spec

The Vega spec ↗ is the JSON that defines your visualization; the Vega spec can be specified inline or by using a string variable.

Vega spec theme configuration

For ease of reusability you can configure a theme that will be injected into the Vega spec. The default theme matches the Blueprint styling of the XY Charts widget, but you can also specify your own custom theme from a string variable, or turn off the theme entirely.

See the vega-themes repository ↗ for examples when building out your own custom themes.

Inline editor

You can use AIP to create the initial version of your Vega chart. With your given data input, you can provide a prompt to AIP such as:

Make me a bar chart of average points per game, bucketed by the number of seasons played.

This will create a chart which you can iterate on with additional AIP prompts:

Remove the gridlines from this chart, and only show number of seasons greater than 4.

If your AIP prompts do not provide the desired result, you can modify the spec directly. Refer to existing Vega examples ↗ and other Vega resources for guidance on how to modify the spec: for instance, you can start from an example and replace the example data with a reference to your input data.

Inline editor: Preview

The Preview tab shows the complete Vega spec with your data inputs and theme data injected into it. You are able to truncate the data for readability, and copy this complete spec to the clipboard. This allows your to verify that the data is in the expected format.

Selection Parameters

The primary reason that Workshop natively supports Vega-Lite is that Vega-Lite supports selection parameters ↗. In the Vega Chart widget, you can configure multiple selection parameters, each of which has a name and an output variable. The output variable can be either an Object Set Filter or a String.

Because selection can be specified in several different places in the spec, this configuration is not auto-injected into the spec. As a builder, you are responsible for including a selection parameter in the spec for each of the configured parameter names.

Here is an example selection parameter that would output range selections on the X-axis:

Copied!
1
2
3
4
5
6
7
8
9
...
"params": [{
  "name": "intervalSelection",
  "select": {
    "type": "interval",
    "encodings": [ "x" ]
  }
}]
...