Helper for working with Vega-Lite (and Vega) within iJavaScript notebooks.

• Vega-Lite Example Gallery
• Vega Example Gallery

(Vega-Lite-Api: creates -> Vega-Lite JSON specifications: creates -> Vega charting specifications: using -> D3 as a visualization kernel)

• Rendering directly as SVG within Jupyter

  • vega.svg((vl) => vl) - to render a chart as SVG directly in Jupyter - using the vega-lite-api
  • vega.svgFromSpec(Object | String) - rendering a chart directly in Jupyter - using a vega-lite specification
  • vega.svgFromSpec(Object | String) - renders a chart directly in Jupyter - using a vega specificiation

• Rendering as HTML / JavaScript through ijs.htmlScript()

  • vega.embed((vl) => vl) - to render a chart in the browser - using the vega-lite-api
  • vega.embedFromSpec(Object | String) - rendering a chart in the browser - using a vega-lite specification
  • vega.embedFromVegaSpec(Object | String) - renders a chart in the browser - using a vega specificiation

• Rendering specifications through the Jupyter Lab mime-type

  • vega.vegaMimeType(Object | String) - render the chart using the Vega mime-type (as png)
  • vega.vegaLiteMimeType(Object | String) - render the chart using the Vega-Lite mime-type (as png)

For example, this is a very simple demonstration for writing a vega-lite chart (the simplest way to get started)

 simpleData = [{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
   {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
   {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];
 
 utils.vega.svg(
 // accept the reference to the vega-lite instance passed
 (vl) => vl
   // render as points
   .markPoint()
       // use simpleData as the data source
       .data(simpleData)
       // title
       .title('Fruit by Yield')
       .width(100)
       .encode(
           // define the x axis as the Qualitative / Numerical 'yield' property
           vl.y().fieldQ('yield'),
           // define the y axis as the Nominative / TextBased 'fruit' property
           vl.x().fieldN('fruit'),
           // define the color series based on the Qualitative / Numerical 'year' property
           vl.color().fieldN('year')
       )
 );

and with simple changes, convert it to a bar graph

• Check out the Vega-Lite tutorials
• See the excellent Vega-Lite-API Observable Notebooks and Jeffrey Heer's Curriculum
• or see the Vega-Lite Examples and Vega Examples
• and of course the documentation is available: Vega-Lite-API, Vega-Lite, Vega

What is Vega-Lite / Vega-Lite-API?

Vega-Lite is a charting library that provides a great deal of flexibility and interaction while also allowing for very simple use cases
(and further simplified with Vega-Lite-Api)

It is built on Vega that uses d3 as a visualization kernel.

Note that Vega-Lite is supported by two options within this library:

• through the vega-lite JSON specification - a high level grammar that creates
  • vega.embed((vl) => vl) - to render a chart in the browser - using the vega-lite-api
  • vega.svg((vl) => vl) - to render a chart as SVG directly in Jupyter - using the vega-lite-api
• through the vega-lite-api - a JavaScript api to write the vega-lite specifications
  • vega.embedFromSpec(Object | String) - rendering a chart in the browser - using a vega-lite specification
  • vega.svgFromSpec(Object | String) - rendering a chart directly in Jupyter - using a vega-lite specification

(Where svg renders directly in Jupyter, and embed uses ijs.htmlScript() to render)

Note that rendering in the browser (as html / javascript), will provide more interactivity options (like export options) while also having consequences in exporting the notebook in some cases.

What is Vega?

True Vega is also supported, providing support for additional capabilities (that to my knowledge cannot be done with vega-lite) such as Radar Charts, Contour Plots, Tree Layouts, Force Plots, and others.

However Vega does not have a JavaScript API:

• vega.embedFromVegaSpec(Object | String) - renders a chart in the browser - using a vega specificiation
• vega.svgFromSpec(Object | String) - renders a chart directly in Jupyter - using a vega specificiation

In the context of Notebooks - is expected that Vega-Lite will be sufficient for most cases.

Embedding vs SVG

SVG versions of charts render directly within Jupyter Notebook (as svg output)

(As a rule - embed... calls and svg... calls can be easily interchanged)

Embedding means the charts run within the browser (through dynamic HTML in the output).

This provides greater flexibility (at the consequence of complexity of splitting computation between jupyter and browser)

As opposed to the SVG version, we can now:

• use vega-embed allowing for downloading of the chart

;

• support for interactions and interactive dashboards

utils.vega.svgFromSpec({
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {"url": "https://vega.github.io/vega-lite/examples/data/sp500.csv"},
  "vconcat": [{
    "width": 480,
    "mark": "area",
    "encoding": {
      "x": {
        "field": "date",
        "type": "temporal",
        "scale": {"domain": {"param": "brush"}},
        "axis": {"title": ""}
      },
      "y": {"field": "price", "type": "quantitative"}
    }
  }, {
    "width": 480,
    "height": 60,
    "mark": "area",
    "params": [{
      "name": "brush",
      "select": {"type": "interval", "encodings": ["x"]}
    }],
    "encoding": {
      "x": {
        "field": "date",
        "type": "temporal"
      },
      "y": {
        "field": "price",
        "type": "quantitative",
        "axis": {"tickCount": 3, "grid": false}
      }
    }
  }]
});

• support for tooltips within the Jupyter cell

utils.vega.embedFromSpec({
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "description": "A scatterplot showing horsepower and miles per gallons that opens a Google search for the car that you click on.",
  "data": {"url": "https://vega.github.io/vega-lite/examples/data/cars.json"},
  "height": 600,
  "width": 400,
  "mark": "point",
  "transform": [{
    "calculate": "'https://www.google.com/search?q=' + datum.Name", "as": "url"
  }],
  "encoding": {
    "x": {"field": "Horsepower", "type": "quantitative"},
    "y": {"field": "Miles_per_Gallon", "type": "quantitative"},
    "color": {"field": "Origin", "type": "nominal"},
    //-- simply by adding the tooltip encoding here
    "tooltip": {"field": "Name", "type": "nominal"},
    "href": {"field": "url", "type": "nominal"}
  }
});

or through the vega lite

FAQ

The following are a series of common questions / issues, put here for visibility.

Passing Objects to vega-lite-api

Note that there are some things that are not supported by the vega-lite-api
(such as grouping)

This is only a problem with the vega-lite-api, as it writes the spec used for vega-lite

In these cases, you can send an object within many of the methods, as it no longer needs to translate how that object should look.

(like sending mark( type:'bar') instead of .markBar() - to allow for tooltips
or passing an object to encode to support grouping)

simpleData = [{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
  {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
  {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];
 
utils.vega.svg((vl) => vl
  // render as points
  .mark({ type: 'bar', tooltip: true})
  .data(simpleData)
  .title('Fruit by Yield')
  .width(100)
  .encode({
    "x": {"field": "fruit"},
    "y": {"field": "yield", "type": "quantitative"},
    "xOffset": {"field": "year"},
    "color": {"field": "year"}
  })
);

Chart Series

Instead of grouping values, you can also create a series of charts instead.

utils.vega.svg((vl) => vl
  // render as points
  .mark({ type: 'arc', innerRadius: 30, tooltip: true})
      .data(simpleData)
      .title('Fruit by Yield')
      .width(100)
      .encode(
        // define the arc on the graph with the Qualitative / Numerical 'yield' property
        vl.theta().fieldQ('yield'),
        // define the y axis as the based on the Qualitative / Numerical 'year' property
        vl.color().fieldN('year'),
        // define the color series Nominative / TextBased 'fruit' property
        vl.column().fieldN('fruit')
      )
);

Other examples can be found under the vega-lite examples and rendered with svgFromSpec or embedFromSpec

Object Formatting / Conversion

Note that vega-lite examples use data at the mark level:

[{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
  {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
  {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];

not at the series level:

[{ year:'2020', apples:20, bananas:15, pears:18 },
 { year:'2021', apples:22, bananas:12, pears:19 }];

If your data is at the series level, you can:

• Transform the data with the group.separateByFields
  • utils.group.separateByFields(fruitSeriesData, 'apples', 'bananas', 'pears');
  • this makes a new field called 'key' that will have values of either apples, bananas or pears
• or using the vega-lite fold transform
  • by adding in the .transform() into the spec - like below

fruitSeriesData = [{ year:'2020', apples:20, bananas:15, pears:18 },
  { year:'2021', apples:22, bananas:12, pears:19 }];

utils.vega.svg((vl) => vl
  .mark({ type: 'arc', innerRadius: 30, tooltip: true})
    .data(fruitSeriesData)

    //-- apples, bananas and pears will now be separate records
    //-- with the new `key` field as either 'apple', 'banana', or 'pears'
    //-- and the new `value` field storing the value of those fields.
    .transform([{ fold: ['apples', 'bananas', 'pears']}])

    .title('Fruit by Yield')
    .width(100)
    .encode(
      // define the arc on the graph with the Qualitative / Numerical 'yield' property
      vl.theta().fieldQ('value'),
      // define the y axis as the Nominative / TextBased 'fruit' property
      vl.color().fieldN('year'),
      // define the color series based on the Qualitative / Numerical 'year' property
      vl.column().fieldN('key')
    )
)

For more:

• Check out the Vega-Lite tutorials
• See the excellent Vega-Lite-API Observable Notebooks and Jeffrey Heer's Curriculum
• or see the Vega-Lite Examples and Vega Examples