Data Visualization with Matplotlib and Seaborn

The Matplotlib mental model: Figure & Axes essential

Here's the moment most people give up on Matplotlib. They copy a snippet, it works; they change one thing, it breaks; they add a second plot and suddenly labels land on the wrong chart. So they paste random plt. lines until something sticks, and quietly decide Matplotlib is just fiddly. It isn't. Almost every one of those frustrations traces back to a single missing idea — and once you have it, the whole library snaps into a shape you can reason about.

The idea is a two-layer split. A Figure is the whole canvas — think of it as the sheet of paper you're drawing on. An Axes is one plot sitting on that paper, with its own x-axis, y-axis, title, and data. The confusing part is the name: "Axes" does not mean the two little x/y lines you'd expect — it means an entire chart. One Figure can hold many Axes (a 2×2 grid of subplots is one Figure with four Axes), and you almost never draw on the Figure directly — you draw on an Axes.

An analogy that sticks: the Figure is an art gallery wall, and each Axes is a framed picture hung on it. You don't paint on the wall; you paint inside a frame. When you say ax.plot(...) you're painting inside that specific frame, so there's never any doubt where the line goes. Compare that to the beginner habit of calling plt.plot(...), which paints on "whichever frame is currently active" — fine with one picture, chaos with several.

The common mistake this section inoculates you against: treating plt as the thing you draw on. Learners write plt.plot(), plt.title(), plt.xlabel() and it feels natural — until they build two charts and the title lands on the wrong one, because plt was pointing at a different "current" Axes than they thought. The fix is to hold a handle to the exact Axes you mean and call methods on it. That's why the very next line you'll see everywhere is fig, ax = plt.subplots(): it hands you both objects — the canvas and the one plot — so you're never guessing which chart you're editing. Internalize "Figure = canvas, Axes = one plot, I always draw on an Axes" and the rest of this chapter is just vocabulary.

Almost all Matplotlib confusion comes from missing one idea. A Figure is the whole canvas; an Axes is a single plot on it (with its own x/y axis). You draw on Axes. A figure can hold several Axes (subplots).

Two API styles — pick the explicit one essential

Matplotlib has two front doors, and picking the wrong one is why so much tutorial code feels like black magic. The stakes are real: the style you learn first becomes the style you reach for under deadline pressure, and one of these two styles quietly falls apart exactly when your work gets serious — when you need two charts, or wrap plotting in a function, or hand a figure to an app. Choose well now and you never have to unlearn a habit.

The first style is pyplot, the plt.-everything approach: plt.plot(x, y), then plt.title(...), then plt.show(). It's seductive because it's short. But notice what's missing — you never named the chart you're drawing on. Pyplot keeps a hidden global variable called the "current axes," and every plt. call secretly edits that. It's like a workshop with one shared workbench: fine when you're the only person building one thing, a disaster the moment there are two projects and you can't tell which bench a tool just modified.

The second style is object-oriented (explicit): fig, ax = plt.subplots() hands you the Figure and the Axes as named variables, and you call methods on them — ax.plot(x, y), ax.set_title(...). It's one extra line, and in return the ambiguity vanishes: every command names the exact chart it touches. There is no "current" anything to lose track of.

The mistake to avoid is assuming the two styles are interchangeable dialects you can freely mix. You can mix them, and the result is the worst of both worlds — some lines edit the object you're holding, others edit the hidden global, and when they disagree you get labels on the wrong plot with no error message to explain why. The honest rule is simple: pick the explicit style and stay in it. The table below lines the two up side by side so you can see that the object-oriented version costs almost nothing and buys you every real-world scenario.

Lab B2.1 · Core charts in Matplotlib essential

Here's a liberating fact: you already know 90% of Matplotlib. People assume they have to memorize dozens of chart functions, but the truth is that every chart you'll draw follows the same four-step recipe — make a Figure and Axes, draw on the Axes, label it, save or return it. Only step two changes: swap ax.plot for ax.bar or ax.hist and you've got a different chart. Learn the recipe once and the "which function?" question shrinks to a small vocabulary list.

Why does that recipe matter more than the individual functions? Because the recipe is where the judgment lives. Choosing ax.plot versus ax.bar isn't a syntax decision — it's a claim about what your data is. A line says "these points are ordered and connected, watch the trend." Bars say "these are separate categories, compare their sizes." A histogram says "forget individual rows, here's the shape of one column's values." Reach for the wrong verb and you've mislabeled your data before you've written a single word of caption.

Think of the Axes as a chef's plate you're building up in layers: first the base (the data — ax.plot), then the seasoning (title and axis labels), then plating for service (savefig to disk). The lab below runs that recipe twice — once for a single line chart, once for a two-panel figure — so you see that going from "one plot" to "a grid of plots" is the same code, just with more Axes handed back to you by plt.subplots(1, 2).

The classic beginner mistake here is skipping the seasoning: drawing the data and calling it done. An unlabeled chart is not evidence, it's decoration — the reader has no idea whether the y-axis is dollars or percent, whether up is good or bad, what the thing even measures. Every real chart gets a title and both axes labelled, every time; it's the cheapest credibility you'll ever buy. Watch for set_title, set_xlabel, and set_ylabel in the code below — they're not optional polish, they're part of the recipe.

charts.pyimport matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(7, 4))
ax.plot(months, revenue, marker="o")     # line: trend over time
ax.set_title("Monthly revenue")
ax.set_xlabel("month"); ax.set_ylabel("$")
fig.savefig("revenue.png", dpi=150, bbox_inches="tight")

# subplots: two Axes on one Figure
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 4))
ax1.bar(regions, totals)          # bar: compare categories
ax2.hist(latencies, bins=30)      # histogram: see a distribution

Lab B2.2 · Seaborn: statistical charts from a DataFrame intermediate

If Matplotlib is a box of art supplies, Seaborn is a photo booth. With raw Matplotlib, drawing "average revenue per region, with error bars" means: group the DataFrame yourself, compute the means, compute the standard errors, position the bars, draw the whiskers, pick the colors. That's a dozen lines of plumbing for a chart every analyst makes fifty times a week. Seaborn's whole reason to exist is to collapse that into one line — and understanding why it can is the key to using it well.

The trick is that Seaborn was designed around a different input than Matplotlib. Matplotlib wants arrays — "here are the x-values, here are the y-values, plot them." Seaborn wants a whole DataFrame plus the names of columns — "here's the data, use the region column for x and the total column for y, and figure out the rest." Because it can see the entire frame, it can do the grouping and the statistics for you: it knows how to split rows by category, average within each group, and draw the spread. You stopped describing pixels and started describing relationships between columns.

An analogy: Matplotlib is like giving someone turn-by-turn driving directions ("go 200 meters, turn left, draw a bar 40 pixels tall"). Seaborn is like giving them a destination ("show me total by region") and trusting the built-in navigation. The single most important word to learn is hue — the parameter that says "and split everything by this category using color." One hue="region" turns a plain distribution into a side-by-side comparison across regions, no loop, no manual color-cycling. It's the closest thing plotting has to a superpower.

The mistake to watch for is reaching for Seaborn for the wrong job. Seaborn shines for statistical, exploratory charts drawn from a tidy DataFrame — distributions, group comparisons, correlations. It is not the tool when you need pixel-perfect control over a bespoke figure for a slide, or a chart type it doesn't offer; there you drop down to the Matplotlib underneath it (Seaborn returns ordinary Axes, so you can). And it expects tidy data — one row per observation, one column per variable, the clean shape you built in B1. Hand it a messy pivot table and it can't do its job. Read the lab as "same DataFrame, five questions, five one-liners" — that density is the payoff.

Seaborn sits on Matplotlib and is built for DataFrames: you pass the frame plus column names, and it handles the statistics and styling. It's the fast path for the charts analysts actually make.

seaborn_charts.pyimport seaborn as sns

sns.barplot(data=df, x="region", y="total")     # aggregates + error bars for you
sns.histplot(data=df, x="latency", bins=30)      # distribution
sns.scatterplot(data=df, x="price", y="qty", hue="region")  # relationship, colored by group
sns.boxplot(data=df, x="region", y="total")     # compare distributions across groups
sns.heatmap(df.corr(numeric_only=True), annot=True)  # correlations between numeric columns

Choosing the right chart intermediate

You can write flawless plotting code and still produce a useless chart. This is the part nobody warns beginners about: the syntax is the easy 10%; the hard 90% is picking a chart type that actually answers the question you're asking. A pie chart of twelve slices, a line connecting unordered categories, a single bar hiding a wildly bimodal distribution — all perfectly valid code, all quietly failing the reader. The stakes are that a well-drawn wrong chart is more dangerous than an ugly one, because its polish earns trust it hasn't earned.

The reframe that fixes this: a chart type is an answer to a specific kind of question, so start from the question, not the picture. Before you type anything, finish the sentence "I want the reader to see ___." If the blank is how something changes over time, that's a line — a line's whole job is to connect ordered points so your eye rides the trend. If it's how categories stack up against each other, that's a bar — because humans are startlingly good at comparing lengths side by side. If it's the shape of one variable's values — where they cluster, how they skew, whether there are outliers — that's a histogram or box or violin. If it's whether two numbers move together, that's a scatter. Match the verb of your question to the chart and you're almost always right.

Why does the human eye care which chart? Because our visual system is precise about some encodings and terrible at others. We judge length and position accurately — which is why bars and dot positions work — but we're clumsy at judging angles and areas, which is exactly what a pie chart asks of us. That single fact is why the table below quietly recommends "bar, usually not pie" for parts-of-a-whole: not fashion, but the wiring of your reader's brain. A pie forces people to compare wedge angles they can't compare; a bar chart of the same shares lets them just read off the lengths.

The mistake this section is really about is defaulting to whatever chart is easy or pretty instead of what the question demands — grabbing a pie because it looks friendly, or a bar of averages because it's one line, when the reader actually needed to see the spread. The strongest tell that you've chosen well is that the chart has one clear message a stranger could state in a sentence. Read the mapping below not as rules to memorize but as a translation table from questions you'll genuinely ask to the picture that answers each one.

The hardest part isn't the code — it's picking a chart that answers your question honestly. Match the chart to the question.

Lab B2.3 · Not lying with charts intermediate

The scariest thing about a misleading chart is that you can draw one by accident. Nobody sets out to deceive when they nudge a y-axis or pick a color scheme — but the reader can't tell an honest mistake from a deliberate spin, and either way they walk away believing something false. The stakes climb the moment a chart leaves your screen: it goes in a report, a board deck, a customer email, and its claim outlives your intentions. Learning the handful of ways charts distort is less about ethics lectures and more about not embarrassing yourself with a graph that says something you didn't mean.

The mental frame that makes this click: a chart is an argument, not a neutral mirror of the data. Every chart makes a claim — "this went up," "these are different," "these two move together" — and the visual choices are the rhetoric of that argument. The single most common distortion is the truncated axis: a bar chart's whole persuasive power is that the reader reads length as value, so if you start the y-axis at 90 instead of 0, a trivial 2% difference balloons into a bar that looks twice as tall as its neighbor. You didn't touch the numbers — you changed the ruler, and the ruler is where the reader's eye actually looks.

Here's the intuition for why the zero baseline is non-negotiable for bars specifically: the bar is a physical stand-in for the quantity, so its bottom must sit at zero or the length stops meaning what the reader thinks it means. (This is why line charts, which encode value by position rather than length, can sometimes justify a non-zero axis — but bars never can.) The same family of tricks includes cherry-picking a flattering date range, and the notorious dual y-axis, where two unrelated series are scaled independently until they appear to dance together — a correlation manufactured purely by the choice of scales.

The mistake to internalize isn't malice, it's carelessness: accepting whatever axis limits the library picks, letting a template's default scale ride, forwarding a chart you didn't sanity-check. The professional habit is the opposite — default to honest scales, start bar axes at zero, label the units so the reader can check you, and ask "could someone read the opposite true thing from this?" The diagram below is the canonical demonstration: the exact same two numbers drawn twice, once with a truncated axis and once from zero, telling flatly opposite stories. Study it until the trick is impossible to un-see.

A chart is an argument. Small choices can mislead — sometimes accidentally. Professional plotting means making the honest version.

Lab B2.4 · Charts for reports, apps & LLM pipelines advanced

Every plotting tutorial ends with plt.show() — and that's exactly the habit that will break your first real application. plt.show() pops up a window and blocks until a human closes it. That's fine at your desk; it's a hung process inside a web server, a frozen batch job in a nightly report, or a timed-out tool call inside an agent. The stakes here are the difference between "a chart I looked at" and "a chart my system can actually use" — and the fix is a small shift in who's in charge of the picture.

The reframe is this: don't display a chart, produce one and hand it back. Instead of a function that draws and shows, write a function that builds a Figure and returns the object — then let whoever called it decide what to do. A report pipeline saves it to a PNG. A Streamlit or Gradio app (B4) passes it to a display component. An agent's code sandbox turns it into an image file to send back to the model. Same figure, three destinations, and none of them wants a blocking pop-up window.

The analogy is a kitchen. plt.show() is a chef who insists on personally carrying every plate to the table and standing there until you finish — the kitchen grinds to a halt. Returning a Figure is a chef who plates the dish and puts it in the pass; the waiter (your caller) takes it wherever it needs to go. That separation — build here, deliver there — is what lets one chart-making function serve a file, a webpage, and an LLM without changing a line. Notice in the lab how make_chart creates its own fig, ax and passes ax=ax to Seaborn: that's the function staying in full control of its figure rather than scribbling on some global "current" plot a caller might not expect.

The mistake, then, is thinking of a chart as something you watch rather than an artifact you hand off. The tell that you've got it right: your plotting code never calls plt.show() and never assumes a screen is attached. This matters far beyond tidiness — it's the reason the exact Seaborn snippets from earlier in this chapter can run untouched inside the Data Analyst Agent's sandbox and come back as a PNG. "Return a Figure" is a small discipline that quietly makes your visualization work portable across reports, apps, and agents alike.

Where visualization plugs into the rest of the course: charts get saved for reports, returned to a web app (B4), or generated by an agent in the code sandbox.

deliver.py# save to a file (reports, email, artifacts)
fig.savefig("report.png", dpi=150, bbox_inches="tight")

# return the figure object to a web framework (Streamlit/Gradio, B4)
def make_chart(df) -> "plt.Figure":
    fig, ax = plt.subplots()
    sns.barplot(data=df, x="region", y="total", ax=ax)
    return fig          # st.pyplot(fig) / Gradio Plot component renders it

# in an agent's code-execution tool, the generated PNG comes back as a file (C2)

Common pitfalls advanced

Almost every visualization bug you'll hit is one of a handful of repeat offenders — which is good news, because it means you can inoculate yourself against most of them in one sitting. The stakes are that these mistakes don't announce themselves: your code runs, a chart appears, and only later does someone point out that the axis lied, the label was missing, or the "distribution" was actually a single misleading average. Knowing the usual suspects turns a vague "something's off" into an instant diagnosis.

It helps to notice these pitfalls come in two flavors, because the fixes are different in kind. The first flavor is mechanical — fighting the tool. Battling the plt. state machine, forgetting labels, passing raw messy data straight into a plot: these are habits, and the cure is a better default habit (hold fig, ax; label everything; clean in Pandas first). The second flavor is perceptual — misleading the human eye even with correct code: a truncated bar axis, a bar of means over bimodal data, a twelve-slice pie. Those aren't bugs the interpreter can catch; they're failures of judgment about how a reader sees. Both flavors show up in the table below, and it's worth reading each row as "the trap, then the reflex that avoids it."

Exercises advanced

import matplotlib.pyplot as plt

months = ["Jan", "Feb", "Mar", "Apr"]
values = [10, 14, 9, 18]

fig, ax = plt.subplots()
ax.plot(months, values, marker="o")
ax.set_title("Monthly active users")
ax.set_xlabel("Month")
ax.set_ylabel("Users (thousands)")
fig.savefig("mau.png", dpi=120, bbox_inches="tight")   # or plt.show()

import matplotlib.pyplot as plt
lines = ["A", "B", "C", "D", "E"]; rev = [30, 22, 18, 15, 5]
fig, ax = plt.subplots()
ax.bar(lines, rev)
ax.set_ylabel("Revenue share (%)"); ax.set_title("Revenue by product line")
plt.show()

import pandas as pd
import seaborn as sns
import matplotlib.pyplot as plt

df = pd.DataFrame({
    "endpoint": ["/a", "/a", "/a", "/b", "/b", "/b"],
    "latency":  [120, 130, 400, 90, 95, 88],
})

ax = sns.boxplot(data=df, x="endpoint", y="latency")
ax.set_title("Latency distribution by endpoint")
plt.show()

import matplotlib.pyplot as plt

labels = ["Q1", "Q2", "Q3"]; vals = [98, 99, 100]

fig, ax = plt.subplots()
ax.bar(labels, vals)
ax.set_ylim(0, 110)      # honest: baseline at 0, so 98 vs 100 looks like ~2%
ax.set_title("Quarterly score (true scale)")
plt.show()
# Misleading version would be: ax.set_ylim(97, 100)  -> a 2% gap looks huge

import matplotlib.pyplot as plt

months = ["Jan", "Feb", "Mar", "Apr"]; signups = [10, 14, 9, 18]
latencies = [120, 130, 400, 90, 95, 88, 110, 100]

fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(10, 4))
ax1.plot(months, signups, marker="o"); ax1.set_title("Signups"); ax1.set_xlabel("Month")
ax2.hist(latencies, bins=6); ax2.set_title("Latency distribution"); ax2.set_xlabel("ms")
fig.suptitle("Weekly report", fontweight="bold")
fig.tight_layout()
fig.savefig("report.png", dpi=150, bbox_inches="tight")

import matplotlib
matplotlib.use("Agg")            # headless backend: no display needed in a pipeline
import matplotlib.pyplot as plt

def save_bar(df, cat_col, val_col, out_path, title=""):
    # Write a bar chart of val_col by cat_col to out_path (PNG). Returns out_path.
    fig, ax = plt.subplots()
    ax.bar(df[cat_col].astype(str), df[val_col])
    ax.set_xlabel(cat_col); ax.set_ylabel(val_col); ax.set_title(title)
    fig.tight_layout()
    fig.savefig(out_path, dpi=120, bbox_inches="tight")
    plt.close(fig)               # release memory in a batch job
    return out_path

# usage (in a pipeline):
# import pandas as pd
# df = pd.DataFrame({"region": ["US","EU"], "rev": [250,120]})
# save_bar(df, "region", "rev", "rev.png", "Revenue by region")

Knowledge check check yourself