Integrations

Using the Vega Lite editor in Chart Builder

Chart Builder uses Vega-Lite, which provides a JSON syntax for creating and styling visualizations. While the Visual Builder interface within Chart Builder on data.world allows one to quickly generate a simple chart, using the Vega Lite editor allows extensive customization of the appearance of the chart.

One important note - once you modify a chart using the Vega Lite editor, the Visual Builder will no longer be accessible. Customize the chart as much as possible in the Visual Builder first before switching to the Vega Lite editor for fine-tuning to keep yourself from needing to do extra work.

This article assumes that you have already enabled the Chart Builder integration on your data.world account. If you have not already, you can enable it from the integrations page while logged into your account.

For a primer on using Chart Builder, please see the Data visualization with Chart Builder.

Getting started

As an example, I've created a project based on a dataset from the US Department of Energy regarding types of energy production throughout the US.

  1. Open up the following query saved to that project: Top 10 states by residential solar energy production

  2. You can then open these query results in Chart Builder using the dropdown menu above the results pane:

    mceclip0.png
  3. Title the chart "Rooftop photovoltaic energy production by US state (top 10)" by clicking on the text that says Untitled chart above.

  4. To the left of the chart, configure the the X axis to use the state field and the Y axis to use the gwh field.

  5. Click on the Options dropdown for the X axis, and under the Sort section, choose Descending by y - gwh.

Screen_Shot_2019-07-18_at_5.42.41_PM.png

You will then see the same chart as below:

Screen_Shot_2019-07-16_at_1.35.42_PM.png

That's a good start, but it's a bit bland and would be difficult to read if projected onto a screen across a conference room. Let's get to work!

Styling the chart title

By default, a Chart Builder adds the title automatically, but does not provide any graphical way to style it. Click on the Vega Lite editor on the top left and you'll see the following entry near the top:

"title": "Rooftop photovoltaic energy production by US state (top 10)"

To transform the title into a field that we can customize, make it into a JSON object by adding curly braces and adding the text property:

"title": {"text": "Rooftop photovoltaic energy production by US state (top 10)" }

The title will look the same as before, but we've laid the foundation for further styling by turning it into a JSON object.

Alignment

The anchor attribute determines the horizontal alignment of the title. Options include:

  • start

  • middle

  • end

In our example, let's align the title on the left side of the chart:

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start"
 }
Font

We'll use the following attributes to style the font used for the title:

  • font - the name of the font

  • fontSize - the size of the font in pixels

  • color - color of the font, given in a CSS-compatible hex code or color name

This attributes are great for matching the chart to an organization's own branding guidelines. Make the following update to give the title that authentic data.world feel:

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start",
   "font": "Lato",   "fontSize": 24,   "color": "#355D8A"
 }
Offset

Our title is looking much better now, but there isn't much space between it and the chart beneath it. Give it some breathing room by adding the offsetattribute. The offset value is the number of pixels between the title and the edge of the chart.

"title": {
   "text": "Rooftop photovoltaic energy production by US state (top 10)",
   "anchor": "start",
   "font": "Lato",
   "fontSize": 24,
   "color": "#355D8A",
   "offset": 40
 }

And here's the result so far:

Styling the axis labels

To modify the axis labels (in this case, the names on the x-axis andnumbers on on the y-axis), we'll add some additional attributes within the configobject already present in our Vega Lite editor. By default, the config object will look like:

"config": {
   "background": "#ffffff",
   "padding": 20,
}

Within that configobject, add a new object called axis to modify the labels on both the X and Y axes at the same time. That object will accept a number of attributes; we'll use the following:

  • labelFontSize - label font size in pixels

  • labelFont - label font name

  • labelColor - color of the label font, given in a CSS-compatible hex code or color name

Our config object now looks like this:

"config": {
   "background": "#ffffff",
   "padding": 20,
   "axis": {     "labelFontSize": 20,     "labelFont": "Lato",     "labelColor": "#6290C3"   }
 }

We modified labels for both axes above, but we can also style axes singly as well. The state names under the X axis are difficult to read with their current orientation, so change that by adding an axisX object within the config object.

Use the labelAngle attribute to control the angle of those labels, providing the number of degrees to rotate them.

"config": {
   "background": "#ffffff",
   "padding": 20,
   "axis": {
     "labelFontSize": 20,
     "labelFont": "Lato",
     "labelColor": "#6290C3",
     "titleFontSize": 24,
     "titleColor": "#333D49",
     "titleFont": "Lato"
   },
   "axisX": {     "labelAngle": 40   }
 }

Styling the axis titles

Our labels are much more readable now, but we need to update those state and gwh axis titles as well. For those, specify the following attributes within the config>axis object:

  • titleFont - axis title font name

  • titleFontSize - axis title font size in pixels

  • titleFontColor - color of the axis title font, given in a CSS-compatible hex code or color name

"config": {
 "background": "#ffffff",
 "padding": 20,
 "axis": {
   "labelFontSize": 20,
   "labelFont": "Lato",
   "labelColor": "#6290C3",
   "titleFontSize": 24,   "titleColor": "#333D49",   "titleFont": "Lato"
   }
}
Screen_Shot_2019-07-16_at_3.15.09_PM.png

Finally, let's edit the title text for each axis (e.g. state and gwh). This will use the column name from our query results by default. In our case, those titles aren't so bad, but in many cases they'll be difficult to read and full of underscores and abbreviations.

Navigate to the encoding object within the Vega Lite editor. It will have a number of nested objects below it already. Find the nested object encoding>x. Add and attribute called title and provide the desired name to that attribute - in this case, give it the value "State Name".

Also add a title attribute under encoding>y and provide the value "Gigawatt hours (GWh)".

Here's our new encoding object:

"encoding": {
 "x": {
   "field": "state",
   "title": "State Name",
   "type": "nominal",
   "sort": {
     "field": "gwh",
     "op": "sum",
     "order": "descending"
      },
   "scale": {
   "type": "linear",
   "zero": true
   }
 },
 "y": {
   "field": "gwh",
   "title": "Gigawatt hours (GWh)",
   "type": "quantitative",
   "scale": {
     "type": "linear",
     "zero": true
     }
   }
 }

And our final chart:

Screen_Shot_2019-07-16_at_3.39.05_PM.png

This tutorial provided some basic styling functionality by accessing the Vega Lite editor in Chart Builder directly, but it can do so much more. Check out the official Vega Lite examples, tutorials, and full documentation for an in depth look.