Matplotlib figure construction
Use the explicit object interface for reusable code:
Figure -> one or more Axes -> Axis objects and data/annotation Artists
pyplot may create the Figure and Axes, but pass ax through helpers rather
than relying on hidden current-figure state.
Workflow
- Define the perceptual question, audience, output dimensions, medium, units,
accessibility needs, and whether axes are shared.
- Inspect data shape, missing values, category order, datetime timezone,
uncertainty, and scale. Do not let implicit string categories or date parsing
silently determine order.
- Create
fig, ax = plt.subplots(...); use Axes methods for marks, labels,
limits, scales, annotations, and legends. Return Figure/Axes or save the
artifact; do not bury global display side effects inside helpers.
- Use data coordinates for values, axes coordinates for annotations tied to
the panel, and figure coordinates only for figure-level layout.
- Set layout and export deliberately. For automation, select a noninteractive
backend before importing pyplot, save with explicit size/DPI/format, and
close figures created in loops or tests.
- Verify semantics and rendering: series count, data values, labels, limits,
scale, legend, accessible colors, output dimensions, and nonempty image.
Invariants
- A Figure is the complete canvas; an Axes is one plotting region; an Axis owns
ticks and scale; almost every visible item is an Artist.
- Do not mix stateful current-Axes calls with explicit Axes ownership in a
reusable function.
- Do not truncate a quantitative bar baseline without explicit disclosure and
a defensible reason.
- Use one shared normalization for color values that must be comparable across
panels.
- Use Seaborn only as a statistical plotting layer when its aggregation and
uncertainty semantics are intended; verify the resulting Matplotlib objects.
import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(7, 4), layout="constrained")
ax.plot(months, values, marker="o", label="Observed")
ax.set(title="Monthly throughput", xlabel="Month", ylabel="Orders")
ax.legend()
fig.savefig("throughput.svg", metadata={"Title": "Monthly throughput"})
plt.close(fig)
Read the object and coordinate model, chart and
scale decisions, and render verification.
1---2name: matplotlib-python3description: >-4 Use for writing, reviewing, debugging, or testing static Python visualization5 with Matplotlib, including Figure, Axes, Axis, Artist, transforms, layouts,6 dates, categorical scales, annotations, color normalization, image export,7 and headless rendering. Do not use for Plotly interactivity, Altair/Vega-Lite8 specifications, dashboard state, or analysis without a Matplotlib artifact.9argument-hint: "[figure intent, data shape, output format, and verification]"10metadata:11 source: https://skillmd.com/skills/schattenspiegel/matplotlib-python12---1314# Matplotlib figure construction1516Use the explicit object interface for reusable code:1718```text19Figure -> one or more Axes -> Axis objects and data/annotation Artists20```2122`pyplot` may create the Figure and Axes, but pass `ax` through helpers rather23than relying on hidden current-figure state.2425## Workflow26271. Define the perceptual question, audience, output dimensions, medium, units,28 accessibility needs, and whether axes are shared.292. Inspect data shape, missing values, category order, datetime timezone,30 uncertainty, and scale. Do not let implicit string categories or date parsing31 silently determine order.323. Create `fig, ax = plt.subplots(...)`; use Axes methods for marks, labels,33 limits, scales, annotations, and legends. Return Figure/Axes or save the34 artifact; do not bury global display side effects inside helpers.354. Use data coordinates for values, axes coordinates for annotations tied to36 the panel, and figure coordinates only for figure-level layout.375. Set layout and export deliberately. For automation, select a noninteractive38 backend before importing pyplot, save with explicit size/DPI/format, and39 close figures created in loops or tests.406. Verify semantics and rendering: series count, data values, labels, limits,41 scale, legend, accessible colors, output dimensions, and nonempty image.4243## Invariants4445- A Figure is the complete canvas; an Axes is one plotting region; an Axis owns46 ticks and scale; almost every visible item is an Artist.47- Do not mix stateful current-Axes calls with explicit Axes ownership in a48 reusable function.49- Do not truncate a quantitative bar baseline without explicit disclosure and50 a defensible reason.51- Use one shared normalization for color values that must be comparable across52 panels.53- Use Seaborn only as a statistical plotting layer when its aggregation and54 uncertainty semantics are intended; verify the resulting Matplotlib objects.5556```python57import matplotlib.pyplot as plt5859fig, ax = plt.subplots(figsize=(7, 4), layout="constrained")60ax.plot(months, values, marker="o", label="Observed")61ax.set(title="Monthly throughput", xlabel="Month", ylabel="Orders")62ax.legend()63fig.savefig("throughput.svg", metadata={"Title": "Monthly throughput"})64plt.close(fig)65```6667Read [the object and coordinate model](references/object-model.md), [chart and68scale decisions](references/decisions.md), and [render verification](references/testing.md).