Styling Altair Charts with the feedzai-altair-theme

If you’ve ever used Altair for Data Visualization, you’ll notice that it provides suitable default styles, removing the burden of adapting them each time you create a chart. However, what if you want to use a coherent set of styles across multiple charts other than the default ones?

At Feedzai, we’ve created an Altair theme based on our internal Data Visualization guidelines — a document with information about different types of charts, recommendations (accessibility included), a style guide for standardized charts, and design tokens (such as font sizes and colors). The Altair theme was originally built to better support data scientists creating charts mainly for communication purposes. Now we are sharing it as an open-source Python package — the feedzai-altair-theme package!

The feedzai-altair-theme package logo (right) was created based on the Altair logo (left).

Altair and Altair Themes

Altair is a Data Visualization package that wraps Vega-Lite for interactive charting in Python. With that in mind, Altair themes are a good way to style multiple charts consistently.

To leverage Altair themes, we need to prepare a Python dictionary (wrapped in a function) with the relevant configuration for our case. Then, we have to register it via the respective API and enable it (globally). If you prefer to use the theme just for a single chart, it is also possible to do it through a context manager with the with statement.

Now, let’s create a small theme in order to exemplify the process of preparing custom Altair themes. This small theme will be focused on the Y-axis.

Set the Configuration for the Theme

First, let’s define a function that returns a dictionary. In this dictionary, we will add the configuration we need to make the charts look the way we want and which will be added to the specification of each chart. In practice, we create a nested dictionary according to the available properties, grouped by configuration types.

For this theme, the Y-axis will not have a domain line, the ticks will be larger than the default ones, and we will have dashed gridlines. We will also remove the gray border around the chart area. All options are described in both the Altair and Vega-Lite documentations.

Register and Enable the New Theme

Once we have the theme function, we need to register it under the chosen name (y_axis) and enable the theme.

Now, for example, when displaying a bar chart, we can see that the Y-axis has a different style than the default one, according to our new theme.

A bar chart with the default Altair theme (left) and the newly created theme (right). The new theme customizes the Y-axis and removes the gray border around the chart area.

To revert to the default Altair theme, we just need to run alt.themes.enable("default").

Packaging Altair Themes

Our theme applied to some charts from the example gallery in the Altair documentation. This theme is a light theme.

To package and distribute Altair themes, in addition to the typical things of a Python package and the theme function, we can use one specific entry point. This entry point is named altair.vegalite.v4.theme, and it is used in the setup.py file (or equivalent).

In this way, there’s no need to import this extra package. The new theme will be available together with the default ones — it is just a matter of enabling it and starting plotting!

feedzai-altair-theme Package

The feedzai-altair-theme package consists of two major parts: the design tokens (which come from our guidelines) and the theme.

The design tokens are defined in the tokens module. Here we can find the spacing scale, font sizes, border widths, and colors, among other tokens. This separate module allows us to reuse these variables throughout the configuration for the Altair theme. In addition, we can easily map these tokens with our guidelines and other supports, ensuring the desired consistency.

Additionally, this package organization allows us to use these tokens in a standalone fashion. Considering the available color palettes, we can import the respective variable from the tokens module, choose a sequential color palette different from the default one, and easily apply it to a specific chart.

The theme itself is in the theme module. As we saw earlier, it consists of a function that returns a dictionary with all the properties that we intend to customize to obtain the desired style for our charts. One helpful thing in Altair/Vega-Lite is that we only need to define what’s relevant since it provides nice defaults for the rest.

Quickstart

To know more about the feedzai-altair-theme package, go to our GitHub repository. Here you can find how to install the package and how to start using it — there’s also a notebook with some examples based on the ones available in the Altair documentation.

After installing the package, run this snippet in a Jupyter notebook, for example, and you’ll see the theme applied to your charts:

To see this theme in action, the TimeSHAP package, also open-sourced by Feedzai, uses the feedzai theme as part of its visualization subpackage (plot).

If you have any questions or feedback, feel free to open an issue in our repository. In case you try it out in your charts, please let us know and share the results below in the comments section!

Rita Costa, Beatriz Feliciano, Javier Pérez, and Sanjay Salomon: thank you so much for your thoughtful feedback that helped me shape this blog post! Beatriz Malveiro: this effort was only possible thanks to your previous work and your help in preparing the Python package — thank you very much!