Customizing Visualizations

Altair’s goal is to automatically choose useful plot settings and configurations so that the user is free to think about the data rather than the mechanics of plotting. That said, once you have a useful visualization, you will often want to adjust certain aspects of it. This section of the documentation outlines some of the ways to make these adjustments.

Global Config vs. Local Config vs. Encoding

There are often two or three different ways to specify the look of your plots depending on the situation. For example, suppose we are creating a scatter plot of the cars dataset:

import altair as alt
from vega_datasets import data
cars = data.cars.url

alt.Chart(cars).mark_point().encode(
    x='Acceleration:Q',
    y='Horsepower:Q'
)

Suppose you wish to change the color of the points to red, and the opacity of the points to 20%. There are three possible approaches to these:

Global Config

First, every chart type has a "config" property at the top level that acts as a sort of theme for the whole chart and all of its sub-charts. Here you can specify things like axes properties, mark properties, selection properties, and more.

Altair allows you to access these through the configure_* methods of the chart. Here we will use the configure_mark() property:

alt.Chart(cars).mark_point().encode(
    x='Acceleration:Q',
    y='Horsepower:Q'
).configure_mark(
    opacity=0.2,
    color='red'
)

There are a couple things to be aware of when using this kind of global configuration:

  1. By design configurations will affect every mark used within the chart
  2. The global configuration is only permissible at the top-level; so, for example, if you tried to layer the above chart with another, it would result in an error.

For more information on top-level configurations, see Top-Level Chart Configuration.

Local Config

If you would like to configure the look of the mark locally, such that the setting only affects the particular chart property you reference, this can be done via a local configuration setting.

In the case of mark properties, the best approach is to set the property as an argument to the mark_* method. Here we will use mark_point():

alt.Chart(cars).mark_point(opacity=0.2, color='red').encode(
    x='Acceleration:Q',
    y='Horsepower:Q'
)

Unlike when using the global configuration, here it is possible to use the resulting chart as a layer or facet in a compound chart.

Local config settings like this one will always override global settings.

Encoding

Finally, it is possible to set chart properties via the encoding channel (see Encodings). Rather than mapping a property to a data column, you can map a property directly to a value using the value() function:

alt.Chart(cars).mark_point().encode(
    x='Acceleration:Q',
    y='Horsepower:Q',
    opacity=alt.value(0.2),
    color=alt.value('red')
)

Note that only a limited set of mark properties can be bound to encodings, so for some (e.g. fillOpacity, strokeOpacity, etc.) the encoding approach is not available.

Encoding settings will always override local or global configuration settings.

Which to Use?

The precedence order for the three approaches is (from lowest to highest) global config, local config, encoding. That is, if a chart property is set both globally and locally, the local setting will win-out. If a property is set both via a configuration and an encoding, the encoding will win-out.

In most usage, we recommend always using the highest-precedence means of setting properties; i.e. an encoding, or a local configuration for properties that are not tied to an encoding. Global configurations should be reserved for creating themes that are applied just before the chart is rendered.

Adjusting Axis Limits

The default axis limit used by Altair is dependent on the type of the data (see, for example, Effect of Data Type on Axis Scales). To fine-tune the axis limits beyond these defaults, you can use the Scale property of the axis encodings. For example, consider the following plot:

import altair as alt
from vega_datasets import data

cars = data.cars.url

alt.Chart(cars).mark_point().encode(
    x='Acceleration:Q',
    y='Horsepower:Q'
)

Altair inherits from Vega-Lite the convention of always including the zero-point in quantitative axes; if you would like to turn this off, you can add a Scale property to the X encoding that specifies zero=False:

alt.Chart(cars).mark_point().encode(
    alt.X('Acceleration:Q',
        scale=alt.Scale(zero=False)
    ),
    y='Horsepower:Q'
)

To specify exact axis limits, you can use the domain property of the scale:

alt.Chart(cars).mark_point().encode(
    alt.X('Acceleration:Q',
        scale=alt.Scale(domain=(5, 20))
    ),
    y='Horsepower:Q'
)

The problem is that the data still exists beyond the scale, and we need to tell Altair what to do with this data. One option is to “clip” the data by setting the "clip" property of the mark to True:

alt.Chart(cars).mark_point(clip=True).encode(
    alt.X('Acceleration:Q',
        scale=alt.Scale(domain=(5, 20))
    ),
    y='Horsepower:Q'
)

Another option is to “clamp” the data; that is, to move points beyond the limit to the edge of the domain:

alt.Chart(cars).mark_point().encode(
    alt.X('Acceleration:Q',
        scale=alt.Scale(
            domain=(5, 20),
            clamp=True
        )
    ),
    y='Horsepower:Q'
).interactive()

For interactive charts like the one above, the clamping happens dynamically, which can be useful for keeping in mind outliers as you pan and zoom on the chart.

Adjusting Axis Labels

Altair also gives you tool to easily configure the appearance of axis labels. For example consider this plot:

import pandas as pd
df = pd.DataFrame({'x': [0.03, 0.04, 0.05, 0.12, 0.07, 0.15],
                   'y': [10, 35, 39, 50, 24, 35]})

alt.Chart(df).mark_circle().encode(
    x='x',
    y='y'
)

To fine-tune the formatting of the tick labels and to add a custom title to each axis, we can pass to the X and Y encoding a custom Axis definition. Here is an example of formatting the x labels as a percentage, and the y labels as a dollar value:

alt.Chart(df).mark_circle().encode(
    x=alt.X('x', axis=alt.Axis(format='%', title='percentage')),
    y=alt.Y('y', axis=alt.Axis(format='$', title='dollar amount'))
)

Additional formatting codes are available; for a listing of these see the d3 Format Code Documentation.

Adjusting the Legend

A legend is added to the chart automatically when the color, shape or size arguments are passed to the encode() function. In this example we’ll use color.

import altair as alt
from vega_datasets import data

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalWidth',
    y='petalLength',
    color='species'
)

In this case, the legend can be customized by introducing the Color class and taking advantage of its legend argument. The shape and size arguments have their own corresponding classes.

The legend option on all of them expects a Legend object as its input, which accepts arguments to customize many aspects of its appearance. One simple example is giving the legend a title.

import altair as alt
from vega_datasets import data

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalWidth',
    y='petalLength',
    color=alt.Color('species', legend=alt.Legend(title="Species by color"))
)

Another thing you can do is move the legend to another position with the orient argument.

import altair as alt
from vega_datasets import data

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalWidth',
    y='petalLength',
    color=alt.Color('species', legend=alt.Legend(orient="left")),
)

You can remove the legend entirely by submitting a null value.

import altair as alt
from vega_datasets import data

iris = data.iris()

alt.Chart(iris).mark_point().encode(
    x='petalWidth',
    y='petalLength',
    color=alt.Color('species', legend=None),
)

Adjusting the width of Bar Marks

The width of the bars in a bar plot are controlled through the size property in the mark_bar():

import altair as alt
import pandas as pd

data = pd.DataFrame({'name': ['a', 'b'], 'value': [4, 10]})

alt.Chart(data).mark_bar(size=10).encode(
    x='name:O',
    y='value:Q'
)

But since mark_bar(size=10) only controls the width of the bars, it might become possible that the width of the chart is not adjusted accordingly:

alt.Chart(data).mark_bar(size=30).encode(
    x='name:O',
    y='value:Q'
)

The width of the chart containing the bar plot can be controlled through two mechanisms:

  1. Setting the width of chart, so the width of the bars are adjusted to fit the width of the chart.
  2. Setting the rangeStep property of the bars in the Scale class. The rangeStep allocates the width (in pixels) for each bar, so the width of the chart becomes the number of bars multiply the rangeStep.

An example using the first mechanism (using width):

alt.Chart(data).mark_bar(size=30).encode(
    x='name:O',
    y='value:Q'
).properties(width=100)

The width of the bars are set using mark_bar(size=30) and the width of the chart is set using properties(width=100)

An example using the second mechanism (using rangeStep):

alt.Chart(data).mark_bar(size=30).encode(
    alt.X('name:N', scale=alt.Scale(rangeStep=100)),
    y='value:Q'
)

The width of the bars are set using mark_bar(size=30) and the width that is allocated for each bar bar in the the chart is set using alt.Scale(rangeStep=100)

Note

If both width and rangeStep are specified, then rangeStep will be ignored.