Saving Altair Charts#
Altair chart objects have a Chart.save() method which allows charts
to be saved in a variety of formats.
JSON format#
The fundamental chart representation output by Altair is a JSON string format;
one of the core methods provided by Altair is Chart.to_json(), which
returns a JSON string that represents the chart content.
Additionally, you can save a chart to a JSON file using Chart.save(),
by passing a filename with a .json extension.
For example, here we save a simple scatter-plot to JSON:
import altair as alt
from vega_datasets import data
chart = alt.Chart(data.cars.url).mark_point().encode(
x='Horsepower:Q',
y='Miles_per_Gallon:Q',
color='Origin:N'
)
chart.save('chart.json')
The contents of the resulting file will look something like this:
{
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
"config": {
"view": {
"continuousHeight": 300,
"continuousWidth": 300
}
},
"data": {
"url": "https://vega.github.io/vega-datasets/data/cars.json"
},
"encoding": {
"color": {
"field": "Origin",
"type": "nominal"
},
"x": {
"field": "Horsepower",
"type": "quantitative"
},
"y": {
"field": "Miles_per_Gallon",
"type": "quantitative"
}
},
"mark": {"type": "point"}
}
This JSON can then be inserted into any web page using the vegaEmbed library.
HTML format#
If you wish for Altair to take care of the HTML embedding for you, you can save a chart directly to an HTML file using
chart.save('chart.html')
This will create a simple HTML template page that loads Vega, Vega-Lite, and vegaEmbed, such that when opened in a browser the chart will be rendered.
For example, saving the above scatter-plot to HTML creates a file with the following contents, which can be opened and rendered in any modern javascript-enabled web browser:
<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
<script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
</head>
<body>
<div id="vis"></div>
<script type="text/javascript">
var spec = {
"$schema": "https://vega.github.io/schema/vega-lite/v5.json",
"config": {
"view": {
"continuousHeight": 300,
"continuousWidth": 300
}
},
"data": {
"url": "https://vega.github.io/vega-datasets/data/cars.json"
},
"encoding": {
"color": {
"field": "Origin",
"type": "nominal"
},
"x": {
"field": "Horsepower",
"type": "quantitative"
},
"y": {
"field": "Miles_per_Gallon",
"type": "quantitative"
}
},
"mark": {"type": "point"}
};
var opt = {"renderer": "canvas", "actions": false};
vegaEmbed("#vis", spec, opt);
</script>
</body>
</html>
You can view the result here: chart.html.
By default, canvas is used for rendering the visualization in vegaEmbed. To
change to svg rendering, use the embed_options as such:
chart.save('chart.html', embed_options={'renderer':'svg'})
Note
This is not the same as alt.renderers.enable('svg'), what renders the
chart as a static svg image within a Jupyter notebook.
Offline HTML support#
By default, an HTML file generated by chart.save('chart.html') loads the necessary JavaScript dependencies from an online CDN location. This results in a small HTML file, but it means that an active internet connection is required in order to display the chart.
As an alternative, the inline=True keyword argument may be provided to chart.save to generate an HTML file that includes all necessary JavaScript dependencies inline. This results in a larger file size, but HTML files generated this way do not require an active internet connection to display.
chart.save('chart.html', inline=True)
Note
Calling chart.save with inline=True requires the vl-convert package.
PNG, SVG, and PDF format#
To save an Altair chart object as a PNG, SVG, or PDF image, you can use
chart.save('chart.png')
chart.save('chart.svg')
chart.save('chart.pdf')
Saving these images requires an additional extension to run the javascript code necessary to interpret the Vega-Lite specification and output it in the form of an image. There are two packages that can be used to enable image export: vl-convert or altair_saver.
vl-convert#
The vl-convert package can be installed with:
conda install -c conda-forge vl-convert-python
or:
pip install vl-convert-python
Unlike altair_saver, vl-convert does not require any external dependencies. See the vl-convert documentation for information and for known limitations.
altair_saver#
Note
altair_saver does not yet support Altair 5.
The altair_saver package can be installed with:
conda install -c conda-forge altair_saver
or:
pip install altair_saver
See the altair_saver documentation for information about additional installation requirements.
Engine Argument#
If both vl-convert and altair_saver are installed, vl-convert will take precedence.
The engine argument to Chart.save() can be used to override this default
behavior. For example, to use altair_saver for PNG export when vl-convert is also
installed you can use:
chart.save('chart.png', engine="altair_saver")
PNG Figure Size/Resolution#
When using chart.save() to create a PNG image, the resolution of the resulting image
defaults to 72 pixels per inch (ppi). To change the resolution of the image, while maintaining
the same physical size, the ppi argument may be provided to chart.save. For example,
to save the image with a resolution of 200 pixels-per-inch:
chart.save('chart.png', ppi=200)
Note
The ppi argument is only supported by the vl-convert engine. It will be ignored if
the altair_saver engine is enabled.
To change the physical size of the resulting image while preserving the resolution, the
scale_factor argument may be used. For example, to save the image at double the default
size at the default resolution of 72 ppi:
chart.save('chart.png', scale_factor=2)