Bar Chart Race¶

Make animated bar chart races in Python with matplotlib or plotly.

(Plotly bar chart races Upcoming in Version 0.2)

Installation¶

Install with either:

pip install bar_chart_race
conda install -c conda-forge bar_chart_race

Quickstart¶

Must begin with a pandas DataFrame containing 'wide' data where:

Every row represents a single period of time
Each column holds the value for a particular category
The index contains the time component (optional)

The data below is an example of properly formatted data. It shows total deaths from COVID-19 for several countries by date.

	Belgium	China	France	Germany	Iran	Italy	Netherlands	Spain	USA	United Kingdom
date
2020-04-08	2240	3337	10887	2349	3993	17669	2255	14792	14704	7111
2020-04-09	2523	3339	12228	2607	4110	18279	2403	15447	16553	7993
2020-04-10	3019	3340	13215	2767	4232	18849	2520	16081	18595	8974
2020-04-11	3346	3343	13851	2894	4357	19468	2653	16606	20471	9892
2020-04-12	3600	3343	14412	3022	4474	19899	2747	17209	22032	10629

Main function - `bar_chart_race`¶

There is one main function, bar_chart_race, which we use to recreate the above video. All of the parameters are shown below.

import bar_chart_race as bcr
df = bcr.load_dataset('covid19_tutorial')
bcr.bar_chart_race(
    df=df,
    filename='covid19_horiz.mp4',
    orientation='h',
    sort='desc',
    n_bars=6,
    fixed_order=False,
    fixed_max=True,
    steps_per_period=10,
    interpolate_period=False,
    label_bars=True,
    bar_size=.95,
    period_label={'x': .99, 'y': .25, 'ha': 'right', 'va': 'center'},
    period_fmt='%B %d, %Y',
    period_summary_func=lambda v, r: {'x': .99, 'y': .18,
                                      's': f'Total deaths: {v.nlargest(6).sum():,.0f}',
                                      'ha': 'right', 'size': 8, 'family': 'Courier New'},
    perpendicular_bar_func='median',
    period_length=500,
    figsize=(5, 3),
    dpi=144,
    cmap='dark12',
    title='COVID-19 Deaths by Country',
    title_size='',
    bar_label_size=7,
    tick_label_size=7,
    shared_fontdict={'family' : 'Helvetica', 'color' : '.1'},
    scale='linear',
    writer=None,
    fig=None,
    bar_kwargs={'alpha': .7},
    filter_column_colors=False)

Save animation to disk or embed into a Jupyter Notebook¶

If you are working within a Jupyter Notebook leave the filename as None and it will be automatically embedded into a Jupyter Notebook.

bcr_html = bcr.bar_chart_race(df=df, filename=None)

Customization¶

There are many options to customize the bar chart race to get the animation you desire. Below, we have an animation where the maximum x-value and order of the bars are set for the entire duration. A custom summary label and perpendicular bar of median is also added.

def period_summary(values, ranks):
    top2 = values.nlargest(2)
    leader = top2.index[0]
    lead = top2.iloc[0] - top2.iloc[1]
    s = f'{leader} by {lead:.0f}'
    return {'s': s, 'x': .95, 'y': .07, 'ha': 'right', 'size': 8}

bcr.bar_chart_race(df_baseball, period_length=1000,
                   fixed_max=True, fixed_order=True, n_bars=10,
                   figsize=(5, 3), period_fmt='Season {x:,.0f}',
                   title='Top 10 Home Run Hitters by Season Played')

More stuff