The Vega-Lite Visualization Library (vega-lite)

Vega-Lite Visualization Library

Module: vegalite

vegalite

Module containing a function to display a relation R as a Vega-Lite chart, if supported by the client, as well as convenience functions for constructing relations to be plotted.

Display function

plot[R]: Given a relation representing a full JSON Vega-Lite schema, richly render it as a Vega-Lite chart. See the Vega-Lite docs (opens in a new tab) for more information on creating a Vega-Lite schema.

Convenience functions

The convenience functions build upon the vegalite_utils and templates to provide a simpler interface to generate common plot types. All convenience functions take in required arguments for that type of plot, along with a CONFIG relation, which includes the data. They each output a JSON relation, which can then be plotted with the plot display function, or further modified by overloading the relation or overriding specific values (see right_override).

bar[X, Y, CONFIG]: Given an X relation specifying the x field (categorical data), a Y relation specifying the y field (quantitative data), and a CONFIG relation (see the section on CONFIG below), gives a relation specifying a bar chart in vegalite.
scatter[X, Y, CONFIG]: Given an X relation specifying the x field (quantitative data), a Y relation specifying the y field (quantitative data), and a CONFIG relation (see the section on CONFIG below), gives a relation specifying a scatter chart in vegalite.
line[X, Y, CONFIG]: Given an X relation specifying the x field (quantitative data), a Y relation specifying the y field (quantitative data), and a CONFIG relation (see the section on CONFIG below), gives a relation specifying a scatter chart in vegalite.

The convenience functions generally combine encoding functions from vegalite_utils along with other utilities with the corresponding vegalite_templates template. The CONFIG relation requires the (:data, DATA) tuple at a minimum, but can also include tuples with any vegalite_utils utility name and its arguments (e.g. (:width, 500), (:x, :axis, :orient, "top"))

Examples

Specify a full JSON Relation

def chart[:data, :values, :[]] = {
  (1, :a, "A");
  (1, :b, 28);
  (2, :a, "B");
  (2, :b, 55);
  (3, :a, "C");
  (3, :b, 43)
}
def chart[:mark, :type] = "bar"
def chart[:mark, :tooltip] = boolean_true // Note: JSON `boolean_true` / `boolean_false`
def chart[:encoding, :x] = {
  (:field, "a");
  (:type, "nominal");
  (:axis, :labelAngle, 0)
}
def chart[:encoding, :y] = {
  (:field, "b");
  (:type, "quantitative")
}
 
def output = vegalite:plot[chart]

Outputs the custom Rel Vega-Lite MIME type along with the chart relation tuples, for the plot to be rendered by Vega-Lite in a client.

Note: JSON-value relations require boolean_true / boolean_false values in tuples (e.g. setting :tooltip to boolean_false), not the logical true / false used in Formulas. Logical true / false cannot be used as values.

Read in JSON example then add data

def chart = parse_json[\"\"\"{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "A simple bar chart with embedded data.",
  "mark": {"type": "bar", "tooltip": false},
  "encoding": {
    "x": {"field": "a", "type": "nominal", "axis": {"labelAngle": 0}},
    "y": {"field": "b", "type": "quantitative"}
  }
}\"\"\"]
 
def data = {("A", 28); ("B", 55); ("C", 43)}
def chart[:data][:values][:[]][i] =
  {(:a, a); (:b, b)} from a,b where enumerate[data](i, a, b)
 
def output = vegalite:plot[chart]

Combines the Vega-Lite JSON specification without data, with data defined in Rel. Outputs the custom Rel Vega-Lite MIME type along with the chart relation tuples.

Simple bar chart

def data:letter = {(1, "A"); (2, "B"); (3, "C")}
def data:number = {(1, 24); (2, 67); (3, 43)}
 
def chart = vegalite:bar[:letter, :number, {:data, data}]
def output = vegalite:plot[chart]

The data is defined in the (field, keys..., value) format (same format used by load_csv), and then plotted with the categorical letter field on the x axis and the quantitative number field on the y axis.

Complex bar chart from CSV data

// penguin dataset
def file_config[:path] = "azure://raidocs.blob.core.windows.net/ml-classification/penguin/penguins_size.csv"
 
def file_config[:schema, :species] = "string"
def file_config[:schema, :island] = "string"
def file_config[:schema, :culmen_length_mm] = "float"
def file_config[:schema, :culmen_depth_mm] = "float"
def file_config[:schema, :flipper_length_mm] = "float"
def file_config[:schema, :body_mass_g] = "float"
def file_config[:schema, :sex] = "string"
 
def chart_config:data = lined_csv[load_csv[file_config]]
def chart_config:color = {(:sex); (:title, "Sex"); (:scale, :schema, "dark2")}
def chart_config:y = {:title, "Count of Penguins"}
def chart_config:title = "🐧"
 
def chart = vegalite:bar[
  :species,
  {:aggregate, "count"},
  chart_config
]
 
def output = vegalite:plot[chart]

Outputs a stacked barchart of the count of penguins broken down by species (bar height) and sex (color within each bar).

The x axis field is set using the fieldname :species.

The {:aggregate, "count"} is using aggregate encoding (opens in a new tab) to plot the number of records for each :species on the y axis instead of a field directly.

The :color encoding is doing three things:

Creating the stacking of the bar chart by coloring each bar by the :sex breakdown within each :species, grouping the chart data by :sex.
The (:color, :title) is being set to "Sex", which will update the title of the legend (included by default) as well as the field name displayed in the tooltip (included with the vegalite_templates:bar relation).
The color scheme is being changed from the default ("tableau10") to the "dark2" scheme. See the Vega documentation (opens in a new tab) for the full list of color schemes available.

The (:y, :title, "Count of Penguins") relation is setting the title of the y axis to "Count of Penguins". This also updates the field name displayed in the tooltip.

The (:title, "🐧") relation sets a title for the chart.

Checkout the vega library.