Data Visualisation with Seaborn#

Introduction#

Warning

seaborn’s object API is still a work-in-progress, so check the version you’re using carefully and note that the API may change relative to what’s shown here.

Here you’ll see how to make plots quickly using the declarative plotting package seaborn. This package is good if you want to make a standard chart from so-called tidy data where you have one row per observation and one columnn per variable.

Note

We recommend you use letsplot for declarative plotting but seaborn is an excellent alternative that builds on matplotlib and so is more customisable.

seaborn is actually built on top of matplotlib so you can also mix code for the two packages.

The rest of this chapter is indebted to the excellent seaborn object notation documentation.

As ever, we start by bringing in the packages we’ll need:

import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import seaborn as sns
import seaborn.objects as so

# Set seed for random numbers
seed_for_prng = 78557
prng = np.random.default_rng(
    seed_for_prng
)  # prng=probabilistic random number generator

Quite a few of the examples we’ll see use a range of additional datasets, so let’s grab those straight away:

tips = sns.load_dataset("tips")
penguins = sns.load_dataset("penguins").dropna()
diamonds = sns.load_dataset("diamonds")
healthexp = (
    sns.load_dataset("healthexp").sort_values(["Country", "Year"]).query("Year <= 2020")
)

Specifying a plot and mapping data#

The most important command in seaborn is Plot(). You specify plots by instantiating a Plot() object and calling its methods. Let’s see a simple example:

(so.Plot(penguins, x="bill_length_mm", y="bill_depth_mm").add(so.Dot()))
_images/4953907aadf07da8a95067d0d8762197b59e2dfc2a29e4f50debbe529c21e4ce.png

This code, which produces a scatter plot, should look reasonably familiar. Just as when using seaborn.scatterplot(), we passed a tidy dataframe (penguins) and assigned two of its columns to the x and y coordinates of the plot. But instead of starting with the type of chart and then adding some data assignments, here we started with the data assignments and then added a graphical element.

Setting properties#

The Dot class is an example of a Mark: an object that graphically represents data values. Each mark will have a number of properties that can be set to change its appearance:

(
    so.Plot(penguins, x="bill_length_mm", y="bill_depth_mm").add(
        so.Dot(color="g", pointsize=4)
    )
)
_images/a6984d37d72f433e1abda11901b7637dd72e9c87311d5290a7f7232bd7937ad5.png

Mapping properties

As with seaborn’s functions, it is also possible to map data values to various graphical properties:

(
    so.Plot(
        penguins,
        x="bill_length_mm",
        y="bill_depth_mm",
        color="species",
        pointsize="body_mass_g",
    ).add(so.Dot())
)
_images/ed80ddd5041931b3c976f525fbf63ec816a8938f6e5ff3a6254dc0a9780d5789.png

While this basic functionality is not novel, an important difference from the function API is that properties are mapped using the same parameter names that would set them directly (instead of having hue vs. color, etc.). What matters is where the property is defined: passing a value when you initialize Dot will set it directly, whereas assigning a variable when you set up the Plot() will map the corresponding data.

Beyond this difference, the objects interface also allows a much wider range of mark properties to be mapped:

(
    so.Plot(
        penguins,
        x="bill_length_mm",
        y="bill_depth_mm",
        edgecolor="sex",
        edgewidth="body_mass_g",
    ).add(so.Dot(color=".8"))
)
_images/9dc6b4971e5a50e9ca856014c42036b7ea0e15efad732077ccb3126b2ca70a3e.png

Defining groups#

The Dot mark represents each data point independently, so the assignment of a variable to a property only has the effect of changing each dot’s appearance. For marks that group or connect observations, such as Line, it also determines the number of distinct graphical elements:

(so.Plot(healthexp, x="Year", y="Life_Expectancy", color="Country").add(so.Line()))
_images/97e2402f8c1a73cf47a1bbd20addc4431a21d808c8948237e9a65e523100b416.png

It is also possible to define a grouping without changing any visual properties, by using group:

(so.Plot(healthexp, x="Year", y="Life_Expectancy", group="Country").add(so.Line()))
_images/51a0c52debf747b7d4450c6ec717d1134bd82f65c723b1b8516dfdb8c15c6ec9.png

Transforming data before plotting#

Statistical transformation#

As with many seaborn functions, the objects interface supports statistical transformations. These are performed by Stat objects, such as Agg():

(so.Plot(penguins, x="species", y="body_mass_g").add(so.Bar(), so.Agg()))
_images/eb96baf0c2e940aca728c9ed84ceab71c16de55ced6366ab8070ad9da79b0cdf.png

In the function interface, statistical transformations are possible with some visual representations (e.g. seaborn.barplot()) but not others (e.g. seaborn.scatterplot()). The objects interface more cleanly separates representation and transformation, allowing you to compose Mark and Stat objects:

(so.Plot(penguins, x="species", y="body_mass_g").add(so.Dot(pointsize=10), so.Agg()))
_images/b726ddc7b080001bc6f87e052992e8a4489dd6a493ba49c2b6449a4292a68bee.png

When forming groups by mapping properties, the Stat transformation is applied to each group separately:

(
    so.Plot(penguins, x="species", y="body_mass_g", color="sex").add(
        so.Dot(pointsize=10), so.Agg()
    )
)
_images/2d003a3a954bac03ddb1f8d6f98b8e99e5d9def08c05ce391107e614cdc1f5cc.png

Resolving overplotting#

Some seaborn functions also have mechanisms that automatically resolve overplotting, as when seaborn.barplot “dodges” bars once hue is assigned. The objects interface has less complex default behavior. Bars representing multiple groups will overlap by default:

(so.Plot(penguins, x="species", y="body_mass_g", color="sex").add(so.Bar(), so.Agg()))
_images/5b522f1bc4d1075303150c76c61f9d9e5a9d9cab060d26ef3f337019cfbe09d8.png

Nevertheless, it is possible to compose the Bar mark with the Agg stat and a second transformation, implemented by Dodge:

(
    so.Plot(penguins, x="species", y="body_mass_g", color="sex").add(
        so.Bar(), so.Agg(), so.Dodge()
    )
)
_images/43c206b11523432010fa65cbaa034ab6d0598cb33b76826554612a1065e04994.png

The Dodge class is an example of a Move transformation, which is like a Stat but only adjusts x and y coordinates. The Move classes can be applied with any mark, and it’s not necessary to use a Stat first:

(so.Plot(penguins, x="species", y="body_mass_g", color="sex").add(so.Dot(), so.Dodge()))
_images/ff7a9cd7a8f9cb706cce62162faaa9c6dccf1a330271ac9f8944969414645d61.png

It’s also possible to apply multiple Move operations in sequence:

(
    so.Plot(penguins, x="species", y="body_mass_g", color="sex").add(
        so.Dot(), so.Dodge(), so.Jitter(0.3)
    )
)
_images/2072678a31888faaedfddd6e721e86b9681087d80bc38a1f00a92de0fc4407ab.png

Creating variables through transformation#

The Agg stat requires both x and y to already be defined, but variables can also be created through statistical transformation. For example, the Hist stat requires only one of x or y to be defined, and it will create the other by counting observations:

(so.Plot(penguins, x="species").add(so.Bar(), so.Hist()))
_images/50a47a348b5d7f1edd3a1af94570c4bb65be34c48289177bb48158f97beb34a6.png

The Hist stat will also create new x values (by binning) when given numeric data:

(so.Plot(penguins, x="flipper_length_mm").add(so.Bars(), so.Hist()))
_images/d1402a0ac9d46b242ebaac30b98e8ec8d1458ba5f5325d014abc034a06ce1efe.png

Notice how we used Bars, rather than Bar for the plot with the continuous x axis. These two marks are related, but Bars has different defaults and works better for continuous histograms. It also produces a different, more efficient matplotlib artist. You will find the pattern of singular/plural marks elsewhere. The plural version is typically optimized for cases with larger numbers of marks.

Some transforms accept both x and y, but add interval data for each coordinate. This is particularly relevant for plotting error bars after aggregating:

(
    so.Plot(penguins, x="body_mass_g", y="species", color="sex")
    .add(so.Range(), so.Est(errorbar="sd"), so.Dodge())
    .add(so.Dot(), so.Agg(), so.Dodge())
)
_images/948bf70fb554dc22d895b7d08e13af893e9f18cfc4ad6a3521a6a6c2a83aae58.png

Orienting marks and transforms#

When aggregating, dodging, and drawing a bar, the x and y variables are treated differently. Each operation has the concept of an orientation. The Plot() tries to determine the orientation automatically based on the data types of the variables. For instance, if we flip the assignment of species and body_mass_g, we’ll get the same plot, but oriented horizontally:

(
    so.Plot(penguins, x="body_mass_g", y="species", color="sex").add(
        so.Bar(), so.Agg(), so.Dodge()
    )
)
_images/508d460af97e0ede69d1bfd2a84b16c6ec935bb2ef8235f9cfaa499858cfa8ad.png

Sometimes, the correct orientation is ambiguous, as when both the x and y variables are numeric. In these cases, you can be explicit by passing the orient parameter to Plot.add():

(
    so.Plot(tips, x="total_bill", y="size", color="time").add(
        so.Bar(), so.Agg(), so.Dodge(), orient="y"
    )
)
_images/e112bbcb1033a28eed509887f1a79635b3b33b1d7e80efcb8d180dde18065af5.png

Building and displaying the plot#

Each example thus far has produced a single subplot with a single kind of mark on it. But Plot() does not limit you to this.

Adding Multiple Layers#

More complex single-subplot graphics can be created by calling Plot.add() repeatedly. Each time it is called, it defines a layer in the plot. For example, we may want to add a scatterplot (now using Dots) and then a regression fit:

(so.Plot(tips, x="total_bill", y="tip").add(so.Dots()).add(so.Line(), so.PolyFit()))
_images/b9068f1f94263387bf61d2e3bd6a91733645dc0a5361a040ada5a265b59b83ee.png

Variable mappings that are defined in the Plot() constructor will be used for all layers:

(
    so.Plot(tips, x="total_bill", y="tip", color="time")
    .add(so.Dots())
    .add(so.Line(), so.PolyFit())
)
_images/d4edb5b7e2dc4b7dbb4b66db36e412019fb17e4d68b459825c67a6cdbee9c6b5.png

Layer-specific mappings#

You can also define a mapping such that it is used only in a specific layer. This is accomplished by defining the mapping within the call to Plot.add() for the relevant layer:

(
    so.Plot(tips, x="total_bill", y="tip")
    .add(so.Dots(), color="time")
    .add(so.Line(color=".2"), so.PolyFit())
)
_images/9deb1fde9b71178c93e54a756a1c2438a49e39480e41eb351736cdc7c4835d1e.png

Alternatively, define the layer for the entire plot, but remove it from a specific layer by setting the variable to None:

(
    so.Plot(tips, x="total_bill", y="tip", color="time")
    .add(so.Dots())
    .add(so.Line(color=".2"), so.PolyFit(), color=None)
)
_images/9deb1fde9b71178c93e54a756a1c2438a49e39480e41eb351736cdc7c4835d1e.png

To recap, there are three ways to specify the value of a mark property: (1) by mapping a variable in all layers, (2) by mapping a variable in a specific layer, and (3) by setting the property directy:

Hide code cell source
from io import StringIO

from IPython.display import SVG

C = sns.color_palette("deep")
f = mpl.figure.Figure(figsize=(7, 3))
ax = f.subplots()
fontsize = 18
ax.add_artist(mpl.patches.Rectangle((0.13, 0.53), 0.45, 0.09, color=C[0], alpha=0.3))
ax.add_artist(mpl.patches.Rectangle((0.22, 0.43), 0.235, 0.09, color=C[1], alpha=0.3))
ax.add_artist(mpl.patches.Rectangle((0.49, 0.43), 0.26, 0.09, color=C[2], alpha=0.3))
ax.text(0.05, 0.55, "Plot(data, 'x', 'y', color='var1')", size=fontsize, color=".2")
ax.text(0.05, 0.45, ".add(Dot(pointsize=10), marker='var2')", size=fontsize, color=".2")
annots = [
    ("Mapped\nin all layers", (0.35, 0.65), (0, 45)),
    ("Set directly", (0.35, 0.4), (0, -45)),
    ("Mapped\nin this layer", (0.63, 0.4), (0, -45)),
]
for i, (text, xy, xytext) in enumerate(annots):
    ax.annotate(
        text,
        xy,
        xytext,
        textcoords="offset points",
        fontsize=14,
        ha="center",
        va="center",
        arrowprops=dict(arrowstyle="->", color=C[i]),
        color=C[i],
    )
ax.set_axis_off()
f.subplots_adjust(0, 0, 1, 1)
f.savefig(s := StringIO(), format="svg")
SVG(s.getvalue())
_images/753f78b31c79926ebfb2d9ee03d642b57cefef971484f817598125900b562019.svg

Faceting and pairing subplots#

As with seaborn’s figure-level functions (seaborn.displot(), seaborn.catplot(), etc.), the Plot() interface can also produce figures with multiple “facets”, or subplots containing subsets of data. This is accomplished with the Plot.facet() method:

(so.Plot(penguins, x="flipper_length_mm").facet("species").add(so.Bars(), so.Hist()))
_images/14db026d984d359d58aa4b0a11a71b5daee23e6f0555200bc23f60c8364edf46.png

Call Plot.facet() with the variables that should be used to define the columns and/or rows of the plot:

(
    so.Plot(penguins, x="flipper_length_mm")
    .facet(col="species", row="sex")
    .add(so.Bars(), so.Hist())
)
_images/59a28c798de346bf13c3b8d2b8d934e67872ed59c1f502bbdcdd9badbf4c0c01.png

You can facet using a variable with a larger number of levels by “wrapping” across the other dimension:

(
    so.Plot(healthexp, x="Year", y="Life_Expectancy")
    .facet(col="Country", wrap=3)
    .add(so.Line())
)
_images/68bd12b472dc717b75cea44c04c59141e9c4e691b3a22f393f19bfd5e011b12c.png

All layers will be faceted unless you explicitly exclude them, which can be useful for providing additional context on each subplot:

(
    so.Plot(healthexp, x="Year", y="Life_Expectancy")
    .facet("Country", wrap=3)
    .add(so.Line(alpha=0.3), group="Country", col=None)
    .add(so.Line(linewidth=3))
)
_images/db2a721b028dce3b381aad9b64b3f6ab94e0dc72212dee7a6cf65524d1357ad8.png

An alternate way to produce subplots is Plot.pair(). Like seaborn.PairGrid(), this draws all of the data on each subplot, using different variables for the x and/or y coordinates:

(
    so.Plot(penguins, y="body_mass_g", color="species")
    .pair(x=["bill_length_mm", "bill_depth_mm"])
    .add(so.Dots())
)
_images/8e315de279cf51036eafa226032a72d4e0196a99eb27513c46f5d9719eec7dcd.png

You can combine faceting and pairing so long as the operations add subplots on opposite dimensions:

(
    so.Plot(penguins, y="body_mass_g", color="species")
    .pair(x=["bill_length_mm", "bill_depth_mm"])
    .facet(row="sex")
    .add(so.Dots())
)
_images/9f97f49cc4c88cbf893cbec3434eb546b062fd16d88b3efd0dcad3a67657eabb.png

Integrating with matplotlib#

There may be cases where you want multiple subplots to appear in a figure with a more complex structure than what Plot.facet() or Plot.pair() can provide. The current solution is to delegate figure setup to matplotlib and to supply the matplotlib object that Plot() should use with the Plot.on() method. This object can be either a matplotlib.axes.Axes, matplotlib.figure.Figure, or matplotlib.figure.SubFigure; the latter is most useful for constructing bespoke subplot layouts:

f = mpl.figure.Figure(figsize=(8, 4))
sf1, sf2 = f.subfigures(1, 2)
(
    so.Plot(penguins, x="body_mass_g", y="flipper_length_mm")
    .add(so.Dots())
    .on(sf1)
    .plot()
)
(
    so.Plot(penguins, x="body_mass_g")
    .facet(row="sex")
    .add(so.Bars(), so.Hist())
    .on(sf2)
    .plot()
)
_images/f8efea769152ec70c07441ba9f3f496c5da45b288969bc7d2900d14b94302b7e.png

Building and displaying the plot#

An important thing to know is that Plot() methods clone the object they are called on and return that clone instead of updating the object in place. This means that you can define a common plot spec and then produce several variations on it.

So, take this basic specification:

p = so.Plot(healthexp, "Year", "Spending_USD", color="Country")

We could use it to draw a line plot:

p.add(so.Line())
_images/d88381084e7d26121c9fdb8b16e7f4288d64b54b532fbdaaab0f9df299b7d82e.png

Or perhaps a stacked area plot:

p.add(so.Area(), so.Stack())
_images/7838f439139662b07e90683dd80a103823ad5b7a1ecd81781ba8b7c4d5f1a643.png

The Plot methods are fully declarative. Calling them updates the plot spec, but it doesn’t actually do any plotting. One consequence of this is that methods can be called in any order, and many of them can be called multiple times.

When does the plot actually get rendered? Plot is optimized for use in notebook environments. The rendering is automatically triggered when the Plot gets displayed in the Jupyter REPL. That’s why we didn’t see anything in the example above, where we defined a Plot but assigned it to p rather than letting it return out to the REPL.

To see a plot in a notebook, either return it from the final line of a cell or call Jupyter’s built-in display function on the object. The notebook integration bypasses :mod:matplotlib.pyplot entirely, but you can use its figure-display machinery in other contexts by calling Plot.show.

You can also save the plot to a file (or buffer) by calling Plot.save.

Customising the appearance#

The new interface aims to support a deep amount of customisation through Plot, reducing the need to switch gears and use matplotlib functionality directly. (But please be patient; not all of the features needed to achieve this goal have been implemented!)

Parameterising scales#

All of the data-dependent properties are controlled by the concept of a Scale and the Plot.scale() method. This method accepts several different types of arguments. One possibility, which is closest to the use of scales in matplotlib, is to pass the name of a function that transforms the coordinates:

(so.Plot(diamonds, x="carat", y="price").add(so.Dots()).scale(y="log"))
_images/c2ff625da5a0335c649955beea409cec6b408055337eb80fcdeb6e1538a2341c.png

Plot.scale() can also control the mappings for semantic properties like color. You can directly pass it any argument that you would pass to the palette parameter in seaborn’s function interface:

(
    so.Plot(diamonds, x="carat", y="price", color="clarity")
    .add(so.Dots())
    .scale(color="flare")
)
_images/2b080c48739840114d5539ca3c40a340e17fa2b6f67b485e8a708404dc2f357a.png

Another option is to provide a tuple of (min, max) values, controlling the range that the scale should map into. This works both for numeric properties and for colors:

(
    so.Plot(diamonds, x="carat", y="price", color="clarity", pointsize="carat")
    .add(so.Dots())
    .scale(color=("#88c", "#555"), pointsize=(2, 10))
)
_images/1c6b9956a4465a10b5789cbd3d2ad90064a4eb5147300d2474de48ec4a249b6b.png

For additional control, you can pass a Scale object. There are several different types of Scale, each with appropriate parameters. For example, Continuous lets you define the input domain (norm), the output range (values), and the function that maps between them (trans), while Nominal allows you to specify an ordering:

(
    so.Plot(diamonds, x="carat", y="price", color="carat", marker="cut")
    .add(so.Dots())
    .scale(
        color=so.Continuous("crest", norm=(0, 3), trans="sqrt"),
        marker=so.Nominal(["o", "+", "x"], order=["Ideal", "Premium", "Good"]),
    )
)
_images/801fc86a4aaf54a940d7f8a306aa4a3c01f3c0436c7fd71b3d5e80337f02d404.png

Customising legends and ticks#

The Scale objects are also how you specify which values should appear as tick labels / in the legend, along with how they appear. For example, the Continuous.tick method lets you control the density or locations of the ticks, and the Continuous.label method lets you modify the format:

(
    so.Plot(diamonds, x="carat", y="price", color="carat")
    .add(so.Dots())
    .scale(
        x=so.Continuous().tick(every=0.5),
        y=so.Continuous().label(like="${x:.0f}"),
        color=so.Continuous().tick(at=[1, 2, 3, 4]),
    )
)
_images/5898d46d4c10601b4183a351767857625dd6b50704fbab6a7e7ab24896f30be0.png

Customising limits, labels, and titles#

Plot() has a number of methods for simple customisation, including Plot.label(), Plot.limit(), and Plot.share():

(
    so.Plot(penguins, x="body_mass_g", y="species", color="island")
    .facet(col="sex")
    .add(so.Dot(), so.Jitter(0.5))
    .share(x=False)
    .limit(y=(2.5, -0.5))
    .label(
        x="Body mass (g)",
        y="",
        color=str.capitalize,
        title="{} penguins".format,
    )
)
_images/8bbec7ac87e82ab7dfd00604160d134bdaddb1daa3c2f720c0363302140a8241.png

Theme customisation#

Finally, Plot() supports data-independent theming through the Plot.theme() method. Currently, this method accepts a dictionary of matplotlib rc parameters. You can set them directly and/or pass a package of parameters from seaborn’s theming functions:

from seaborn import axes_style

so.Plot().theme({**axes_style("whitegrid"), "grid.linestyle": ":"})
_images/a7f7e97613a98925f9871b4e956984f2e391dc81facc86310c1e2fc51ea70320.png