Vega at a Glance
Source code is located at the end of this topic.
This tutorial provides an overiew of Vega and a simple example to visualize tweets in the EMEA geographic region:
Defining the Source Data
The Vega JSON structure maps data to geometric primitives.
A first task is to specify the data source. You can either define data statically or use a SQL query. This examples uses a SQL query to get tweet geolocation information from a tweets database:
The resulting SQL columns can be referenced in other parts of the specification to drive visualization elements. In this example, the projected columns are goog_x
and goog_y
, which are renamed x
and y
, and rowid, which is a requirement for hit-testing.
Creating a Visualization using Vega
The Vega specification for this example includes the following top-level properties:
height
andwidth
, which define the height and width of the visualization area.data
, which defines the data source. The SQL data described above is defined here with the labeltweets
for later referencing.marks
, which describes the geometric primitives used to render the visualization.scales
, which are referenced by marks to map input domain values to appropriate output range values.
Here is the full Vega specification used in this example:
The following sections describe the top-level Vega specification properties.
Define the Visualization Area Dimensions
The width
and height
properties define a visualization area 384
pixels wide and 564
pixels high:
The scales
position encoding properties map the marks
into this visualization area.
Define the Marks
The marks
property defines visualization geometric primitives. The OmniSci Vega implementation defines the following primitive types:
lines
A linepoints
A pointpolys
A polygonsymbol
A geometric symbol, such as a circle or square
Each primitive type has a set of properties that describe how the primitive is positioned and styled.
This example uses points to represent the tweets
data:
Points support the following properties; not all are included in the example:
x
The x position of the point in pixels.y
The y position of the point in pixels.z
The depth coordinate of the point in pixels.fillColor
The color of the point.fillOpacity
The opacity of the fill, from transparent (0
) to opaque (1
).opacity
The opacity of the point as a whole, from transparent (0
) to opaque (1
).size
The diameter of the point in pixels.
The points in the example reference the tweets
SQL data and use the x
and y
columns from the SQL to drive the position of the points. The positions are appropriately mapped to the visualization area using scales as described in Scale Input Domain to Output Range. The fill color is set to blue
and point size is set to three pixels.
Scale Input Domain to Output Range
The scales
definition maps data domain values to visual range values, where the domain
property determines the input domain for the scale. See the d3-scale reference for background information about how scaling works.
This example uses linear scales to map mercator-projected coordinates into pixel coordinates for rendering.
The x
and y
scales use linear
interpolation to map point x- and y-coordinates to the width
and height
of the viewing area. The width
and height
properties are predefined keywords that equate to the range [0, <current width>]
and [0, <current height>]
.
After completing the Vega specification, you send the JSON structure to the backend for rendering.
Connecting to the Server and Rendering the Visualization
The following steps summarize the rendering and visualization sequence:
Instantiate the
MapdCon
object for connecting to the backend.Call the connect method with server information, user credentials, and data table name.
Provide the
renderVega()
callback function toconnect()
and include the Vega specification as a parameter.Display the returned PNG image in you client browser window.
OmniSci uses Apache Thrift for cross-language client communication with the backend. Include the browser-connector.js, connector API, which includes Thrift interface libraries and the renderVega()
function:
The following example encapsulates the connect, render request, and response handling sequence:
Next Steps
This example demonstrated the basic concepts for understanding and using Vega. To become comfortable with Vega, try this example using your own OmniSci instance, changing the MapdCon()
parameters according to match your host environment and database.
As you gain experience with Vega and begin writing your own applications, see the Reference for detailed information about Vega code.
Source Code
HTML
Vega at a Glance index.html
Last updated