abudaan/vega-specs

Create Vega3 specs with javascript and export them to JSON, BSON and YAML

Vega specs

Creating Vega 3 specs with javascript and export them to JSON, BSON, YAML or a template. The template format can be handy when you want to configure or generate your specs before you pass them to the Vega runtime. For instance if you serve the specs from a server you can configure the path to data sources or images to match the folder structure of your server.

Table of Contents

• vega-specs
  • Table of Contents
  • Javascript Vega specifications
  • Specs as JSON, BSON or YAML
  • Experiments
    • experiment 2
    • experiment 2a
    • experiment 3
    • experiment 4
    • experiment 5
    • experiment 6
    • experiment 7
    • experiment 8
    • experiment 9
    • experiment 10
  • Project setup
  • Run locally

(toc created by gh-md-toc)

Javascript Vega specifications

Crafting Vega specifications (specs) in JSON can be very cumbersome; you can not comment out certain parts for testing and you can't add inline documentation.

That is why I build up my Vega specs from separate javascript objects:

const signals = [
    ...
];

const data = [
    ...
];

const marks = [
    ...
];

const projections = [
    ...
];

const scales = [
    ...
];

...

Then I use an export function that returns the Vega spec as Javascript object. In some cases it can be handy to pass arguments, for instance for dynamically setting the path to data sources and images:

export default function (args) => {
    const {
        dataPath,
        imagePath
    } = args;

    const data = [{
        name: 'map',
        url: `${dataPath}map.topo.json`,
    }];

    const marks = [{
        type: 'image',
        name: 'schools_image',
        encode: {
            enter: {
                url: {
                    value: `${imagePath}school.png`,
                },
                ...
            }
        }
    }]

    // the rest of you spec objects ...

    return {
        $schema: 'https://vega.github.io/schema/vega/v3.0.json',
        width: 720,
        height: 720,
        autosize: 'none',
        scales,
        signals,
        data,
        marks,
        projections,
        ...
    }
};

Then I can import the spec anywhere and add it to the Vega runtime:

import createSpec from '../src/specs/spec5';

const spec = createSpec({
    dataPath: '../../data',
    imagePath: '../../img',
});

const view = new vega.View(vega.parse(spec))
    .renderer('canvas')
    .initialize('vega-div')
    .hover()
    .run();

To render separate specs that can listen to each other's signals I use vega-multi-view.

Specs as JSON, BSON or YAML

I have added functionality to print the spec as JSON to a new browser tab to allow you to open and save the spec as separate .vg.json file:

If you want to convert the spec before runtime into a JSON file there is a gulp script for that as well: gulp create_specs. It converts all specs in the specs folder; the JSON files are written to the same folder. (The script will output a YAML version of the specs as well, these are used in the vega-multi-view-server)

Experiments

I have created a few experiments that all address different functionality of Vega, I will add more documentation as soon as I can find the time to do it.

experiment 2

Using webfonts and css in Vega specs using SVG renderer. [live demo]

experiment 2a

Using webfonts and css in Vega specs using canvas renderer. [live demo]

experiment 3

Render tooltips on top of a map using Vega-tooltip. [live demo]

experiment 4

Render a Vega spec to a layer in Leaflet using leaflet-vega. [live demo]

experiment 5

Upper part of this example [live demo]

experiment 6

Controller part of this example [live demo]

experiment 7

This example split into 2 separate specs, but the upper spec still receives the signal of the controller spec. [live demo]

experiment 8

Scatterplot with selectable date range; 2 separate specs. [live demo]

experiment 9

Display hover signal in another (non-related) spec [live demo]

experiment 10

Same as experiment 8 but now the specs get read from the dataset attribute of the body, see the source of the html file. [live demo]

This is an ongoing project: more tests will follow.

Project setup

• css: contains both the sass files and the compiled css file
• data: the data sources that are used in the specs
• experiments: the code of the experiments as described above, every experiment has its own sub folder
• img: the images that are used in the specs
• node_modules: you will see this folder after you've run yarn install or npm install
• scripts: contains a script that converts the Vega specs from javascript to json files, used by gulp.
• specs: all Vega specs both in javascript and json format
• gulp.babel.js: contains build and watch scripts
  • gulp build_css compiles sass to a single css
  • gulp build_all builds all experiments
  • gulp build_js -e 3 build single experiment, in this case experiment 3
  • gulp watch_all watch all experiments; compiles all experiments continuously:
  • gulp watch_all -e 9 single out the experiment that you're working on; in this case only experiment #9 is watched
  • gulp create_specs converts all specs in javascript format to JSON files

Run locally

If you have Python installed you can start the SimpleHTTPServer at port 9001 with the command npm run server