Skip to main content

Define a vega-lite visual

In this tutorial, you will use vega() to visualise a tabular datastream. You will

  • define a chart using vega(), and
  • launch a solution and observe the results.

This lesson will assume that you have an empty project and asset which you can to deploy to a workspace named 03_07_03_define_a_vega_visual with the following command:

edk template deploy -ycw 03_07_03_define_a_vega_visual

What is Vega-lite?

Vega-lite is an open sourced declarative language, or high-level grammar for interactive data visualisation. Many different types of visualisations can easily be defined using vega-lite. The Elara EDK libraries, make it simple to create Vega-lite visualisations from datastreams.

Define and deploy a template

To use the vega() methods you will first perform the following steps:

  1. define a datasource using a similar pattern as your previous My Source definition.
  2. set the value of based on some generated data of type Map<string, { date: Date, category: string, value: bigint }>() value.
  3. add the datasource to a template

In an asset, perform the above steps to create the resulting Typescript code:

import { SourceBuilder, Template } from "@elaraai/core"

const my_source = new SourceBuilder("My Source")
    .value({
        value: new Map(Array.from({ length: 100 }).map((_, index) => (
            [`${index}`, {
                date: new Date(new Date().valueOf() + index * 3600 * 1000),
                category: `category ${index % 4}`,
                value: BigInt(Math.round(200 * Math.sin(Math.PI * index / 100))),
            }]
        )))
    })

export default Template(my_source)

Define a vega-lite view

You can define a single vega-lite view using the vega() method of VegaBuilder(), by taking the following steps:

  1. add a new layout "01 - My Layout", using a prefix to maintain order
  2. add a vega to the layout using the vega() method of the LayoutBuilder
  3. configure a vega view, by using the view() method of the VegaBuilder
  4. define the datastream for the visualisation with fromStream() method of the VegaViewBuilder
  5. configure a scatter chart with the following series each from a VegaFieldEncodingBuilder
    1. build an x series, sort in ascending order, from date
    2. build a y series, from value
    3. build a color series, from value
    4. build a size series, from value
  6. add the new layout to the template

In the definition 01 - My Layout add the above changes:

import { SourceBuilder, Template, LayoutBuilder } from "@elaraai/core"

const my_source = new SourceBuilder("My Source")
    .value({
        value: new Map(Array.from({ length: 100 }).map((_, index) => (
            [`${index}`, {
                date: new Date(new Date().valueOf() + index * 3600 * 1000),
                category: `category ${index % 4}`,
                value: BigInt(Math.round(200 * Math.sin(Math.PI * index / 100))),
            }]
        )))
    })

const my_layout = new LayoutBuilder("01 - My Layout")
    .vega("My Chart", builder => builder
        .view(builder => builder
            .fromStream(my_source.outputStream())
            .scatter({
                x: builder => builder.value(fields => fields.date).sort('ascending'),
                y: builder => builder.value(fields => fields.value),
                color: builder => builder.value(fields => fields.value),
                size: builder => builder.value(fields => fields.value)
            })
        )
    )

export default Template(my_source, my_layout);

Navigate to the layout URL located within the tenant you deployed to see your chart:

workspaces/03_07_03_define_a_vega_visual/layouts/01%20-%20My%20Layout/

Series Attributes

Many of the type specific attributes of a series can be customised within each series, with the available methods being exposed by VegaFieldEncodingBuilder depending on the data type of the chosen field.

For example, given the x series above, the following methods could be used to customise based on the vega-lite specification rules:

LayoutDescription
title()Define the series title
format()Define the series label format.
timeUnit()Define the series time unit, limited to DateTimeType
sort()Define the series sort order.
bin()Define binning to perform on the series.
aggregate()Define the aggregation to perform.
normalize()Define the series stacking/
type()Define the data type, for example ('nominal', 'ordinal', 'quantitative').

Define layered vega-lite views

You can define a layered vega-lite visualisations using the layered() method of VegaBuilder(), by taking the following steps:

  1. add a new layout "02 - My Other Layout", using a prefix to maintain order
  2. add a vega to the layout using the vega() method of the LayoutBuilder
  3. configure a layered vega, by using the layered() method of the VegaBuilder
    1. configure a vega view, by using the view() method of the VegaLayeredBuilder 2. define the datastream for the visualisation with fromStream() method of the VegaViewBuilder 3. configure a column chart with the following series each from a VegaFieldEncodingBuilder
      1. build an x series, sort in ascending order, from date
      2. build a y series, from value
      3. build a color series, from category
    2. configure a second vega view, by using the view() method of the VegaLayeredBuilder 2. define the datastream for the visualisation with fromStream() method of the VegaViewBuilder 3. configure a scatter chart with the following series each from a VegaFieldEncodingBuilder
      1. build an x series, sort in ascending order, from date
      2. build a y series, from value
      3. build a color series, from value
      4. build a size series, from value
  4. add the new layout to the template

In the definition 02 - My Other Layout add the above changes:

import { SourceBuilder, Template, LayoutBuilder } from "@elaraai/core"

const my_source = new SourceBuilder("My Source")
    .value({
        value: new Map(Array.from({ length: 100 }).map((_, index) => (
            [`${index}`, {
                date: new Date(new Date().valueOf() + index * 3600 * 1000),
                category: `category ${index % 4}`,
                value: BigInt(Math.round(200 * Math.sin(Math.PI * index / 100))),
            }]
        )))
    })

const my_layout = new LayoutBuilder("01 - My Layout")
    .vega("My Chart", builder => builder
        .view(builder => builder
            .fromStream(my_source.outputStream())
            .scatter({
                x: builder => builder.value(fields => fields.date).sort('ascending'),
                y: builder => builder.value(fields => fields.value),
                color: builder => builder.value(fields => fields.value),
                size: builder => builder.value(fields => fields.value)
            })
        )
    )

const my_other_layout = new LayoutBuilder("02 - My Other Layout")
    .vega("My Chart", builder => builder
        .layered(builder => builder
            .view(builder => builder
                .fromStream(my_source.outputStream())
                .column({
                    x: builder => builder.value(fields => fields.date).sort('ascending'),
                    y: builder => builder.value(fields => fields.value),
                    color: builder => builder.value(fields => fields.category),
                })
            )
            .view(builder => builder
                .fromStream(my_source.outputStream())
                .scatter({
                    x: builder => builder.value(fields => fields.date).sort('ascending'),
                    y: builder => builder.value(fields => fields.value),
                    color: builder => builder.value(fields => fields.value),
                    size: builder => builder.value(fields => fields.value)
                })
            )
        )
    )

export default Template(my_source, my_layout, my_other_layout);

Navigate to the layout URL located within the tenant you deployed to see your chart:

workspaces/03_07_03_define_a_vega_visual/layouts/02%20-%20My%20Other%20Layout/

Define a vega-lite specification

You can define a vega-lite specification to display in the user-interface spec() method of VegaViewBuilder(), by taking the following steps:

  1. add a new layout "03 - My Last Layout"
  2. add a vega to the layout using the vega() method
  3. configure a vega view, by using the view() method of the VegaBuilder
  4. define the datastream for the visualisation with fromStream() method of the VegaViewBuilder
  5. configure a spec chart with returning a valid vega-lite specification, based on the field names provided in fields
  6. add the new layout to the template

In the definition 03 - My Last Layout add the above changes:

import { SourceBuilder, Template, LayoutBuilder } from "@elaraai/core"

const my_source = new SourceBuilder("My Source")
    .value({
        value: new Map(Array.from({ length: 100 }).map((_, index) => (
            [`${index}`, {
                date: new Date(new Date().valueOf() + index * 3600 * 1000),
                category: `category ${index % 4}`,
                value: BigInt(Math.round(200 * Math.sin(Math.PI * index / 100))),
            }]
        )))
    })

const my_layout = new LayoutBuilder("01 - My Layout")
    .vega("My Chart", builder => builder
        .view(builder => builder
            .fromStream(my_source.outputStream())
            .scatter({
                x: builder => builder.value(fields => fields.date).sort('ascending'),
                y: builder => builder.value(fields => fields.value),
                color: builder => builder.value(fields => fields.value),
                size: builder => builder.value(fields => fields.value)
            })
        )
    )

const my_other_layout = new LayoutBuilder("02 - My Other Layout")
    .vega("My Chart", builder => builder
        .layered(builder => builder
            .view(builder => builder
                .fromStream(my_source.outputStream())
                .column({
                    x: builder => builder.value(fields => fields.date).sort('ascending'),
                    y: builder => builder.value(fields => fields.value),
                    color: builder => builder.value(fields => fields.category),
                })
            )
            .view(builder => builder
                .fromStream(my_source.outputStream())
                .scatter({
                    x: builder => builder.value(fields => fields.date).sort('ascending'),
                    y: builder => builder.value(fields => fields.value),
                    color: builder => builder.value(fields => fields.value),
                    size: builder => builder.value(fields => fields.value)
                })
            )
        )
    )

const my_last_layout = new LayoutBuilder("03 - My Last Layout")
    .vega("My Chart", builder => builder
        .view(builder => builder
            .fromStream(my_source.outputStream())
            .spec((fields) => ({
                $schema: "https://vega.github.io/schema/vega-lite/v5.json",
                transform: [],
                mark: { type: "point" },
                encoding: {
                    x: { field: fields.date, type: 'temporal' },
                    y: { field: fields.value, type: 'quantitative' },
                    color: { field: fields.value, type: 'quantitative', },
                }
            }))
        )
    )
export default Template(my_source, my_layout, my_other_layout, my_last_layout);

Navigate to the layout URL located within the tenant you deployed to see your chart:

workspaces/03_07_03_define_a_vega_visual/layouts/03%20-%20My%20Last%20Layout/

Observe results

If you do not have access to Elara, the results of the above are shown below:

Example solution

The code for this tutorial is available below:

Next steps

In the next tutorial, you will use the tab() layout to contain multiple visualisations.

On this page