search

altair-viz / altair_saver

Altair extension for saving charts in a variety of formats.
BSD 3-Clause "New" or "Revised" License
95 stars 33 forks source link

readme

Altair Saver

This repo is no longer maintained. Since Altair 5.2, the functionality of Altair Saver is now available in Altair via the vl-convert package. Most of the functionality has been available since 5.0, and the main addition in 5.2 was PDF export. See the docs on how to save charts for more details

github actions github actions code style black Open in Colab

This packge provides extensions to Altair for saving charts to a variety of output types. Supported output formats are:

Usage

The altair_saver library has a single public function, altair_saver.save(). Given an Altair chart named chart, you can use it as follows:

from altair_saver import save

save(chart, "chart.vl.json")              # Vega-Lite JSON specification
save(chart, "chart.vg.json")              # Vega JSON specification
save(chart, "chart.html")                 # HTML document
save(chart, "chart.html", inline=True)    # HTML document with all JS code included inline
save(chart, "chart.png")                  # PNG Image
save(chart, "chart.svg")                  # SVG Image
save(chart, "chart.pdf")                  # PDF Image

Renderer

Additionally, altair_saver provides an Altair Renderer entrypoint that can display the above outputs directly in Jupyter notebooks. For example, you can specify a vega-lite mimetype (supported by JupyterLab, nteract, and other platforms) with a PNG fallback for other frontends as follows:

alt.renderers.enable('altair_saver', fmts=['vega-lite', 'png'])

Installation

The altair_saver package can be installed with:

$ pip install altair_saver

Saving as vl.json and as html requires no additional setup.

To install with conda, use

$ conda install -c conda-forge altair_saver

The conda package installs the NodeJS dependencies described below, so charts can be saved to png, svg, and pdf without additional setup.

Additional Requirements

Output to png, svg, and pdf requires execution of Javascript code, which altair_saver can do via one of two backends.

Selenium

The selenium backend supports the following formats:

To be used, it requires the Selenium Python package, and a properly configured installation of either chromedriver or geckodriver.

On Linux systems, this can be setup as follows:

$ pip install selenium
$ apt-get install chromium-chromedriver

Using conda, the required packages can be installed as follows:

$ conda install -c conda-forge python-chromedriver-binary

The conda approach additionally requires separate installation of a compatible version of Google Chrome, which cannot be done via conda.

Selenium supports other browsers as well, but altair-saver is currently only tested with Chrome.

NodeJS

The nodejs backend supports the following formats:

It requires NodeJS, along with the vega-lite, vega-cli, and canvas packages.

First install NodeJS either by direct download or via a package manager, and then use the npm tool to install the required packages:

$ npm install vega-lite vega-cli canvas

Using conda, node and the required packages can be installed as follows:

$ conda install -c conda-forge vega-cli vega-lite-cli

These packages are included automatically when installing altair_saver via conda-forge.