Key Takeaways — Chapter 10: matplotlib Architecture

1. Everything in matplotlib Is an Object

The threshold concept: every visible element on a matplotlib chart — every line, every dot, every bar, every letter, every tick mark — is a Python object with methods and properties. You do not draw on a canvas; you configure a tree of Artist objects, and matplotlib renders the tree. Once you internalize this, every method call in matplotlib makes sense as "setting a property on some object in the tree." This is the single mental shift that makes matplotlib make sense.

2. The Three-Layer Architecture

Matplotlib is built as three layers: Backend (the part that actually draws pixels or vectors — Agg for raster, PDF/SVG for vector, Qt/Tk for interactive), Artist (the tree of Python objects that represents your chart), and Scripting (the pyplot convenience wrapper for one-liner charts). You interact with the Artist layer most of the time, pyplot occasionally, and the backend almost never.

3. Figure, Axes, and Axis Are Different Things

Figure is the top-level container — the whole image (PNG, PDF page). Axes (plural, with an 's') is a single plotting area within a Figure — what most people call "a chart." Axis (singular, no 's') is one of the two numerical axes within an Axes (x-axis or y-axis). A simple single-chart figure has 1 Figure, 1 Axes, and 2 Axis objects. The plural-vs-singular naming is confusing, but the distinction is essential: you work with Axes most of the time, and Axis only for specialized tick formatting.

4. The Canonical fig/ax Pattern

The single most important pattern in all of matplotlib:

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(10, 6))
ax.plot(x, y)
ax.set_title("...")
ax.set_xlabel("...")
ax.set_ylabel("...")
fig.savefig("chart.png", dpi=300, bbox_inches="tight")

Memorize this. It is the foundation for every example in Part III. plt.subplots() creates the Figure and Axes; every subsequent call is a method on fig or ax explicitly. This is the object-oriented (OO) API, and it is preferred over pyplot for anything beyond the simplest exploratory chart.

5. Prefer the OO API Over Pyplot

The pyplot API (plt.plot(), plt.title(), plt.xlabel()) maintains hidden state — a "current Figure" and "current Axes" — which causes bugs in multi-panel or multi-figure code. The object-oriented API (fig, ax = plt.subplots() followed by ax.plot(), ax.set_title(), etc.) makes the state explicit and is the recommended default. Pyplot is fine for five-line exploratory charts; the OO API is better for everything else.

6. figsize and dpi Are the Most Important Figure Parameters

figsize=(width, height) in inches controls the size of the figure. Match it to the chart type: wide for time series (12, 4 or similar), square for scatter (6, 6), tall for ranked bar charts with many categories. dpi controls resolution: 100 for display, 300 for print. Use dpi=300 when saving for publication.

7. Save with savefig(dpi=300, bbox_inches="tight")

The canonical save call is fig.savefig("chart.png", dpi=300, bbox_inches="tight"). The dpi=300 gives print-quality output. The bbox_inches="tight" crops the saved image to the actual content, removing excess whitespace. These two arguments should be your defaults for anything that will be shared. The output format is determined by the file extension: PNG for raster web/display, PDF for print publications, SVG for editing in vector tools.

8. Method Calls on Axes Do Most of the Work

The vast majority of your matplotlib code is method calls on Axes objects. Plot methods: ax.plot, ax.scatter, ax.bar, ax.hist, ax.boxplot. Labeling methods: ax.set_title, ax.set_xlabel, ax.set_ylabel. Limit methods: ax.set_xlim, ax.set_ylim. Grid and spine methods: ax.grid, ax.spines["top"].set_visible(False). Learning Axes methods is 80% of learning matplotlib, and the official matplotlib.axes.Axes API reference page is the single most valuable page in the docs.

9. The Ugly Climate Plot Is the Starting Point

The twelve-line Section 10.9 code that produces the climate time series is the "before picture" for Part III. Every subsequent chapter in Part III will improve on it: Chapter 11 introduces the specific line chart options, Chapter 12 adds styling and typography, Chapter 13 introduces multi-panel layouts. By the end of Part III, the same data will produce a publication-quality figure that meets every standard from Parts I and II. The progression from ugly to polished is the arc of the rest of Part III.

matplotlib's documentation includes a gallery (matplotlib.org/stable/gallery/) with hundreds of example charts and their full source code — browse for the chart type you need, copy the code, modify it. The API reference (matplotlib.org/stable/api/) lists every class and method with arguments and examples. Experienced matplotlib users rely on the gallery for starting points and the API reference for specific parameter lookups. Stack Overflow fills in the gaps with answered questions, though many older Stack Overflow answers use the pyplot state machine and need mental translation to the OO API. Learning to navigate these resources is a core matplotlib skill.