Advanced Plotting: Using Vega-Lite Directly¶

The pdvega API is rather simplistic at the moment; it doesn’t give easy access to many of the features that Vega-Lite supports. In the future, we would like to tie pdvega to the Altair project, which would allow plot outputs to be adjusted flexibly from within a Python API.

In the meantime, it is possible to make more fine-tuned adjustments to your plot specifications by working directly in the specification dictionary.

For example, consider this plot:

from vega_datasets import data
iris = data.iris()

iris.vgplot(kind='scatter', x='sepalLength', y='petalLength', c='species')

Vega-Lite’s default behavior is to include the zero-value in the scale, unless the user explicitly turns that requirement off in the JSON spec.

pdvega is not designed to give easy access to every option available in the Vega-Lite schema, but it is possible to modify the specification manually. We can access the raw Vega-Lite specification from any plot using the spec attribute. For convenience, there is also a spec_no_data attribute that returns the spec without the the embedded data:

>>> plot = iris.vgplot(kind='scatter', x='sepalLength', y='petalLength', c='species')
>>> plot.spec_no_data
{'$schema': 'https://vega.github.io/schema/vega-lite/v2.json',
'encoding': {'color': {'field': 'species', 'type': 'nominal'},
 'x': {'field': 'sepalLength', 'type': 'quantitative'},
 'y': {'field': 'petalLength', 'type': 'quantitative'}},
'height': 300,
'mark': 'circle',
'selection': {'grid': {'bind': 'scales', 'type': 'interval'}},
'width': 450}

This dictionary contains the specification that tells the vega-lite renderer how to map data to visual components in the plot. You can read more details on the Vega-Lite website. In particular, if you look at the options for Vega-Lite scales, you can see that there is a "scale" property of the “x” encoding which allows turning off the zero behavior. Knowing this, we can update the specification manually to get the desired result:

plot.spec['encoding']['x']['scale'] = {'zero': False}
plot

Using this type of approach, you can customize your plots in any way that Vega-Lite allows.

This is admittedly a bit of a clumsy solution for plot customization; mucking around in the internals of the JSON specification requires a deep knowledge of the vega-lite schema, and the renderer is not very forgiving if and when you make an error or typo. In the future, we plan to make pdvega plots output Altair objects, which will allow this sort of customization to be done much more cleanly with Altair’s Python API.

Skipping `vgplot` entirely¶

If you would like to skip pdvega’s vgplot API entirely and build your Vega-Lite plot from scratch, pdvega’s Axes object lets you do this directly. For example:

from pdvega import Axes

spec = {
  '$schema': 'https://vega.github.io/schema/vega-lite/v2.json',
  'mark': 'point',
  'encoding': {
    'color': {'field': 'species', 'type': 'nominal'},
    'x': {'field': 'petalWidth', 'type': 'quantitative'},
    'y': {'field': 'petalLength', 'type': 'quantitative'}
  },
  'height': 300,
  'width': 450,
  # this selection is what makes the plot interactive
  'selection': {'grid': {'bind': 'scales', 'type': 'interval'}},
}

# Build the vgplot specification
Axes(spec, iris)

For ideas on what sort of visualizations you can create in this way, check out the specifications on the Vega-Lite examples page. The Vega online editor is also a useful resource for developing visualizations directly in Vega or Vega-Lite.

Advanced Plotting: Using Vega-Lite Directly¶

Skipping vgplot entirely¶

Skipping `vgplot` entirely¶