Bar Chart Race Python Package Official Release

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 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 built some for my coronavirus dashboard.

YouTube Tutorial

This post is available as a tutorial on YouTube

Installation

Install with:

pip install bar\_chart\_race

This is the first major release — version 0.1.0

>>> import bar\_chart\_race as bcr
>>> bcr.\_\_version\_\_
'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.

df = bcr.load\_dataset('covid19\_tutorial')
df

Basic Bar Chart Race

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

bcr.bar\_chart\_race(df)

Change orientation

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

bcr.bar\_chart\_race(df, orientation='v')

Change sort order

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

bcr.bar\_chart\_race(df, sort='asc')

Limit bars

Limit the number of bars plotted with n_bars.

bcr.bar\_chart\_race(df, n\_bars=6)

Fix order

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

bcr.bar\_chart\_race(df, fixed\_order=['Iran', 'USA', 'Italy', 
                                    'Spain', 'Belgium'])

Fixed max

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

bcr.bar\_chart\_race(df, fixed\_max=True)

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.

bcr.bar\_chart\_race(df, steps\_per\_period=20, period\_length=200)

Interpolate period

Linearly interpolate the period label.

bcr.bar\_chart\_race(df, interpolate\_period=True)

Plotting properties

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

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')

Bar properties

Bar properties can also be set.

bcr.bar\_chart\_race(df, bar\_kwargs={'alpha': .2, 'ec': 'black', 'lw': 3})

Period label format

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

bcr.bar\_chart\_race(df, period\_fmt='%b %-d, %Y')

Custom summary label

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

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)

Perpendicular line

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

def func(values, ranks):
    return values.quantile(.9)

bcr.bar\_chart\_race(df, perpendicular\_bar\_func=func)

Published with Jupyter to Medium

This blog post was published with jupyter_to_medium, a python package I createdto automate the process of publishing Jupyter Notebooks as Medium blog posts.