Installing and Using pdvega

To install and use pdvega run the following commands:

$ pip install pdvega
$ jupyter nbextension install --sys-prefix --py vega3

The first command installs the pdvega Python package along with its dependencies (Pandas and vega3). The second command above installs the vega3 Jupyter notebook extension, which is required for pdvega plots to display automatically in the notebook.

Using pdvega in the Jupyter Notebook

When pdvega and vega3 are correctly installed, you can create a visualization within the Jupyter notebook by executing a cell with a plot command as the last statement in the cell. For example:

import pandas as pd
import pdvega  # adds vgplot attribute to Pandas objects

data = pd.Series([1,2,3,2,3,4,3,4,5])
data.vgplot()

You can also explicitly call the plot.display() method to display a plot saved in a variable:

plot = data.vgplot()
plot.display()

Using pdvega in JupyterLab

JupyterLab is the next phase of evolution for the Jupyter notebook. For reasons related to its under-the-hood implementation, the current version of pdvega will not work in JupyterLab: the main reason is that the new MIME-based rendering used by JupyterLab is not yet supported in the vega3 library that pdvega depends on.

We hope to address this incompatibility soon!

Using pdvega Outside Jupyter

If you wish to use pdvega outside the Jupyter notebook, you can save the plot specification to a JSON file:

import json
plot = data.vgplot()
json.dump(plot.spec, 'plot.json')

The resulting plot specification can then be rendered within an HTML page using the vega-embed Javascript package.

Saving Visualizations to PNG or SVG

To save a visualization to PNG, you can use the link generated below the rendered plot. Programmatic saving of figures is not currently supported from within Python, though it is possible using the vl2png and vl2svg command-line tools provided in the vega-lite npm package.