Matplotlib
Matplotlib is the most famous library for data visualization with python. It allows to create literally every type of chart with a great level of customization. This page provides some general tips that can be applied on any kind of chart made with matplotlib like customizing titles or colors. If you're looking at creating a specific chart type, visit the gallery instead.
⏱ Quick start
Matplotlib is the most famous python data visualization library. It is widely used and most of other viz libraries (like seaborn) are actually built on top of it.
Once installed, matplotlib must be imported, usually using import matplotlib.pyplot as plt. You can then use use the functions available in the plt object.
# library
import numpy as np
import matplotlib.pyplot as plt
# Create data
x=range(1,6)
y=[1,4,6,8,4]
# Area plot
plt.fill_between(x, y)
plt.show()
Basic vocabulary
The figure below describes the anatomy of a matplotlib charts. It names all the main components, names that you need to know to understand the documentation properly.
⚠️ Disclaimer: this figure comes from the very complete matplotlib documentation. Have a look at it for a thorough explanation on how this library works.
Anatomy of a matplotlib chart: all the basic vocabulary you need to know to understand the documentation properly
Two distinct APIs
There are 2 main ways to build a chart with matplotlib: the pyplot API and the object-oriented API.
➡️ pyplot API
Pyplot is a collection of functions, each function applying a change to a figure. For instance, plt.barh() will build a barplot and plt.title() will add a title to it.
# import libraries
import pandas as pd
import matplotlib.pyplot as plt
# Create a data frame
df = pd.DataFrame ({'Group': ['A', 'B', 'C', 'D', 'E'], 'Value': [1,5,4,3,9]})
# Create horizontal bars
plt.barh(y=df.Group, width=df.Value);
# Add title
plt.title('A simple barplot');
➡️ object oriented API
The object oriented API usually starts by initializing one Figure object and one or more Axes object using the subplot() function. Then the methods of those objects will be used to apply changes to the chart.
# import libraries
import pandas as pd
import matplotlib.pyplot as plt
# Create a data frame
df = pd.DataFrame ({'Group': ['A', 'B', 'C', 'D', 'E'], 'Value': [1,5,4,3,9]})
# Initialize a Figure and an Axes
fig, ax = plt.subplots()
# Fig size
fig.set_size_inches(9,9)
# Create horizontal bars
ax.barh(y=df.Group, width=df.Value);
# Add title
ax.set_title('A simple barplot');
See how the syntax slightly differs between both options? (plt.title versus ax.set_title(). This is pretty confusing and I advise to have a look to the official documentation for a more thorough explanation. In the gallery, both APIs are used.
Customizing titles
The title is a key part of a good chart. It has to summarize its key message in a few words. Always avoid to simply repeat what is displayed on each axis. Try to provide some more insight allowing to understand the main result instead.
The post #190 goes in depth on how to customize the matplotlibtitle. All the main types of change are descried: changing its color, adding a subtitle, using math formulas and so on. Give it a go!
Annotation
Annotation is a key part of a great visualization. It transforms a simple chart in a whole piece of story telling. Before you share your graph with anyone, make sure the key insight are highlighted with labels, shapes or color.
All those kind of annotation are built thanks to various matplotlib functions like annotate() or add_patch(). The blogposts showcased below should get you started with it.
✨ Cheatsheets
It's pretty hard to remember all the matplotlib associated vocabulary. The cheatsheet section is here to help, with a few sheets that you'll probably want to use on a daily basis.
Custom fonts
Using custom fonts adds a nice touch to your graph and make it shine among all the other plots using defaults. The blog-post below will guide you through the process: installing a font and calling it with matplotlib functions.
Add margin around a matplotlib chart
It is a common struggle to deal with the margins around the chart. Fortunately this is pretty straightforward thanks to the subplots_adjust() function as explained in the examples below.
Split the figure in subplots
It can be really useful to split your graphic window in several parts, in order to display several charts in the same time. The subplot() function of matplotlib allows to do it quickly with a great level of customization.
Additional note: how to remove some unused entries in a grid using the ax.remove() function:
Available style sheets
Matplotlib comes with a set of 26 pre-built themes to style your chart easily. This post is dedicated to this feature, explaining how to use plt.style.use() to pick a theme up.
Customizing axis
Matplotlib allows every kind of axis configuration. It is mainly done thanks to the tick_params(), xticks() and xlabels() functions. The post #191 will guide you through all the possibilities.
Customizing the legend
If you have several colors or marker on your chart, you can't escape the hassle of building a nice legend. The blogpost linked below should help for all the most common use cases like positioning the legend, adding and customizing a title to it, controling markers and labels and more.
Insert images in a matplotlib graph
It can be very useful to insert one or several images in a matplotlib graph. It can be used for the graph caption or even inside the chart area to provide more context.
Please find below a complete tutorial explaining how to proceed using the PIL and io libraries, and a real life usage of this technique to produce a beautiful & polished figure.
Contact
👋 This document is a work by Yan Holtz. You can contribute on github, send me a feedback on twitter or subscribe to the newsletter to know when new examples are published! 🔥