Vega Tutorials

These tutorials introduce you to common Vega specification patterns so you can start creating visualizations quickly and easily. Each tutorial uses a code example that demonstrates a particular Vega feature or pattern. The Getting Started with Vega tutorial covers basic Vega concepts and serves as the foundation for some of the tutorials that follow, and introduces you to the API for communication with the backend. Other tutorials provide more in-depth information about specific Vega implementations.

Use these tutorials and the MapD Charting Examples to gain a better understanding of Vega by experimenting with them to create new visualizations on your own OmniSci system and database. You can also Try Vega to make adjustments to Vega code and see real-time changes in charts.

For information about the Vega specification syntax and properties, see Vega Reference.

Tutorial Framework

Because the tutorials focus on the Vega specification, they use a simple client implementation that sends the render request to the OmniSci server and handles the response:

Common index.html
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>OmniSci</title>
    <meta charset="UTF-8">
  </head>
  <body>
    <script src="js/browser-connector.js"></script>
    <script src="js/vegaspec.js"></script>
    <script src="js/vegademo.js"></script>

    <script>
    document.addEventListener('DOMContentLoaded', init, false);
    </script>
  </body>
</html>
Common vegademo.js
function init() {
    var conn = new MapdCon()
        .protocol("http")
        .host("my.host.com")
        .port("6273")
        .dbName("omnisci")
        .user("omnisci")
        .password("changeme")
        .connect(function(error, con) {
          con.renderVega(1, JSON.stringify(exampleVega), vegaOptions, function(error, result) {
            if (error) {
              console.log(error.message);
            }
            else {
              var blobUrl = `data:image/png;base64,${result.image}`
              var body = document.querySelector('body')
              var vegaImg = new Image()
              vegaImg.src = blobUrl
              body.append(vegaImg)
            }
          });
        });
}

The renderVega() function sends the exampleVega JSON structure described in the tutorials. Getting Started with Vega covers Vega library dependencies and the renderVega() function in more detail.

Finding the Cause of Errors

On a connection error, you can view the error message to determine the cause of the error. To determine the cause of Vega specification errors, catch and handle the renderVega() exception.

Available Tutorials

  • Vega at a Glance - Provides an overiew of Vega and a simple example to visualize tweets.
  • Getting Started with Vega - Maps a continuous, quantitative input domain to a continuous output range. Uses the same visualization as Vega at a Glance, but elaborates on the runtime environment and implementation steps.
  • Getting More from Your Data - Builds on the Getting Started with Vega tutorial by color-coding tweets according to language.
  • Creating More Advanced Charts - Introduces Symbol Type marks by creating a heatmap visualization of political donations.
  • Using the Poly Marks Type - Shows how to use the Polys Type marks, which uses an implicit polygon data table format. The visualization in the tutorial is a map of zip codes, color-coded according to average political contribution amount.
  • Vega Accumulator - Describes the three modes of accumulation rendering and provides some implementation examples. The data used contains information about political donations, including party affiliation, the amount of the donation, and location of the donor.
  • Using Transform Aggregation - Shows how to create Vega-based visualizations with render properties that are driven by aggregated statistics. Use Vega transform aggregation and formula expressions to automate the process of gathering statistical information about a rendered query.
  • Improving Rendering with SQL Extensions - Describes how to use SQL extension functions in Vega to map meters to pixels and improve map rendering.