Bin transforms

As with Aggregate Transforms, there are two ways to apply a bin transform in Altair: within the encoding itself, or using a top-level bin transform.

An common application of a bin transform is when creating a histogram:

import altair as alt
from vega_datasets import data

movies = data.movies.url

alt.Chart(movies).mark_bar().encode(
    alt.X("IMDB_Rating:Q", bin=True),
    y='count()',
)

But a bin transform can be useful in other applications; for example, here we bin a continuous field to create a discrete color map:

import altair as alt
from vega_datasets import data

cars = data.cars.url

alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color=alt.Color('Acceleration:Q', bin=alt.Bin(maxbins=5))
)

In the first case we set bin = True, which uses the default bin settings. In the second case, we exercise more fine-tuned control over the bin parameters by passing a Bin object.

If you are using the same bins in multiple chart components, it can be useful to instead define the binning at the top level, using transform_bin() method.

Here is the above histogram created using a top-level bin transform:

import altair as alt
from vega_datasets import data

movies = data.movies.url

alt.Chart(movies).mark_bar().encode(
    x='binned_rating:O',
    y='count()',
).transform_bin(
    'binned_rating', field='IMDB_Rating'
)

And here is the transformed color scale using a top-level bin transform:

import altair as alt
from vega_datasets import data

cars = data.cars.url

alt.Chart(cars).mark_point().encode(
    x='Horsepower:Q',
    y='Miles_per_Gallon:Q',
    color='binned_acc:O'
).transform_bin(
    'binned_acc', 'Acceleration', bin=alt.Bin(maxbins=5)
)

The advantage of the top-level transform is that the same named field can be used in multiple places in the chart if desired. Note the slight difference in binning behavior between the encoding-based bins (which preserve the range of the bins) and the transform-based bins (which collapse each bin to a single representative value.

Transform Options

The transform_bin() method is built on the BinTransform class, which has the following options:

Property	Type	Description
as	anyOf(FieldName, array(FieldName))	The output fields at which to write the start and end bin values. This can be either a string or an array of strings with two elements denoting the name for the fields for bin start and bin end respectively. If a single string (e.g., "val") is provided, the end field will be "val_end".
bin	anyOf([True], BinParams)	An object indicating bin properties, or simply true for using default bin parameters.
field	FieldName	The data field to bin.