Official Release of bar_chart_race - A Python Package for Creating Animated Bar Chart Races

 

I'm excited to announce the official release of bar_chart_race, a python package for creating bar chart races. In this post, I'll cover many of the major available options. Navigate to the official documentation for a full breakdown of all of the options.

Motivation

Bar chart races have become very popular over the last year and no python package existed to create them. I also built some for my coronavirus dashboard.

Installation

Install with:

pip install bar_chart_race
In [1]:
import bar_chart_race as bcr
bcr.__version__
Out[1]:
'0.1.0'
 

Data must be in a particular format

In order to use bar_chart_race, your data must be in 'wide' pandas DataFrame 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)

Load data

A few sample datasets are available to download via the load_dataset function. The covid19_tutorial dataset contains the total deaths due to COVID-19 of selected countries over a period of 10 days.

In [2]:
df = bcr.load_dataset('covid19_tutorial')
df
Out[2]:
  Belgium China France Germany Iran Italy Netherlands Spain USA United Kingdom
date                    
2020-04-03 1143 3326 6520 1275 3294 14681 1490 11198 7418 3611
2020-04-04 1283 3330 7574 1444 3452 15362 1656 11947 8387 4320
2020-04-05 1447 3333 8093 1584 3603 15887 1771 12641 9489 4943
2020-04-06 1632 3335 8926 1810 3739 16523 1874 13341 10783 5385
2020-04-07 2035 3335 10343 2016 3872 17127 2108 14045 12798 6171
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
 

Basic Bar Chart Race

Once you have data in the correct format, you can pass it directly to bar_chart_race.

In [3]:
bcr.bar_chart_race(df)
Out[3]:
 

Change orientation

By default, bars are horizontal, but can be made vertical with the orientation parameter.

In [4]:
bcr.bar_chart_race(df, orientation='v')
Out[4]:
 

Change sort order

Set sort to 'asc' to change the order of the bars.

In [5]:
bcr.bar_chart_race(df, sort='asc')
Out[5]:
 

Limit bars

Limit the number of bars plotted with n_bars.

In [6]:
bcr.bar_chart_race(df, n_bars=6)
Out[6]:
 

Fix order

Fix the order of the bars for the duration of the animation by setting fixed_order to a list.

In [7]:
bcr.bar_chart_race(df, fixed_order=['Iran', 'USA', 'Italy', 'Spain', 'Belgium'])
Out[7]:
 

Fixed max

Fix the maximum value for the entire duration of the animation.

In [8]:
bcr.bar_chart_race(df, fixed_max=True)
Out[8]:
 

Smoothness

By default, 10 frames are used per time period with the entire period lasting 500 milliseconds (half of a second). Both of these are changed below.

In [9]:
bcr.bar_chart_race(df, steps_per_period=20, period_length=200)
Out[9]:
 

Interpolate period

Linearly interpolate the period label.

In [10]:
bcr.bar_chart_race(df, interpolate_period=True)
Out[10]:
 

Plotting properties

bar_chart_race uses matplotlib for all of the underlying plotting. Many properties can be set by using parameters common to matplotlib.

In [11]:
bcr.bar_chart_race(df, 
                   figsize=(5, 3), 
                   dpi=100, 
                   label_bars=False,
                   period_label={'x': .99, 'y': .1, 'ha': 'right', 'color': 'red'},
                   title='COVID-19 Deaths by Country')
Out[11]:
 

Bar properties

Bar properties can also be set.

In [12]:
bcr.bar_chart_race(df, bar_kwargs={'alpha': .2, 'ec': 'black', 'lw': 3})
Out[12]:
 

Period label format

The period label can be formatted with date directives or new-style string formatting.

In [13]:
bcr.bar_chart_race(df, period_fmt='%b %-d, %Y')
Out[13]:
 

Custom summary label

Add a custom label to the plot that summarizes the current time period.

In [14]:
def summary(values, ranks):
    total_deaths = int(round(values.sum(), -2))
    s = f'Total Deaths - {total_deaths:,.0f}'
    return {'x': .99, 'y': .05, 's': s, 'ha': 'right', 'size': 8}

bcr.bar_chart_race(df, period_summary_func=summary)
Out[14]:
 

Perpendicular line

A single perpendicular bar can be added to summarize each period as well.

In [15]:
def func(values, ranks):
    return values.quantile(.9)

bcr.bar_chart_race(df, perpendicular_bar_func=func)
Out[15]:
Close

Register for a free account

Upon registration, you'll get access to four free courses.