Widget Tricks - Heatmaps with Vega-Lite

Vega-Lite is a high-level grammar of interactive graphics. It provides a concise, declarative JSON syntax to create an expressive range of visualizations for data analysis and presentation.

ods-vega-lite-chart widget, in combinaison with ods-adv-analysis to get the data, allows adding Vega-Lite charts into your pages.

This first resource is an introduction and pre-requisite to understand key concepts of Vega-Lite within ODS.

We consider the usage of ods-adv-analysis as a pre-requisite of this resource. Documentation available here

Vega-Lite presentation

Vega-Lite works with a json block that contains the entire description of the chart. It looks like this:

{
    '$schema': 'https://vega.github.io/schema/vega-lite/v2.json',
    'data': {
        'name': 'data'
    },
    'height': 300,
    'config': {
        ...
    },
    'mark': 'rect',
    'encoding': {
        'y': ...,
        'x': ...,
        'color': ...,
        'size': ...
    }
}
  • data is the data from your ods-adv-analysis
  • height the height of the chart. The width is 100% of the container
  • mark is the type of chart, rect for heatmaps, circle for bubble maps, it can be line, area, text etc… See mark documentation
  • encoding is the axis, scale, legend, and all specific settings of the visualisation

Encoding block is the most important, it contains your axis settings, color and size settings, and the legend

An example of minimal encoding for an heatmap :

'encoding': {
        'y': {
            'field': 'date',
            'timeUnit': 'month',
            'type': 'ordinal'
        },
        'x': {
            'field': 'date',
            'timeUnit': 'hours',
            'type': 'ordinal'
        },
        'color': {
            'field': 'count',
            'aggregate': 'sum',
            'type': 'quantitative'
        }
    }
}
  • y axis are the months, taken from the date field of the data
  • x axis are the hours of the day, taken from the date field of the data
  • the heatmap is colored by computing the sum of count field from the data, for each month and hours.
  • type: quantitative the type of scale of colors.

The resulting values are a quantity (a sum, an average etc…). See other encoding types in the documentation.

In brief, scale types are :

  • quantitative: numerical values and quantities
  • temporal: specific to full dates and datetimes to render timeseries
  • ordinal: values that you can order (ex: Jan, Feb, Mar, Apr…)
  • nominal: values that you can name (ex: Male, Female)

Global configuration

'config': {
        'view': {
            'stroke': 'transparent',
            'strokeWidth': 0
        },
        'axis': {
            'grid': true,
            'domain': false,
            'labelFontSize':14,
            'labelFont':'Roboto, Helvetica, Arial, sans-serif'
        }
    }
}

Optional, but useful to customize the final rendering. Here grid: true set a grid canvas with X and Y lines. domain: false remove the baseline between the visualization and the axis legends. See the documentation for more personalization

Heatmap: with linear scale

The default scale is linear. It can get additional properties like the scheme. All available scale colors (schemes) can be found in the scheme documentation.

'color': 
    'scale': {
        'scheme': 'blueorange',
        ...
    },
    ...

Heatmap: with quantile scale

Quantile scale is a type of scale that can be set in the color property.

'color': 
    'scale': {
        'type': 'quantile',
        ...
    },
    ...

Bubblemaps

To switch to a bubblemap:

  • set the grid to false in the config view
  • set the mark type to circle
  • in addition to the color property, a new mark property is necessary to change the size of the circles: size.

size mark property documentation here. It’s very similar to the color property, it expects an aggregate and field option to be able to size circles depending on your data. It also accepts different scale types (quantile, power, log etc…).

With text axis

Axis can be from any type. It only needs to be set as a facet and part of the ods-adv-analysis.