matplotlib – Data & Science skill for AI agents

Matplotlib

Overview

Matplotlib is Python's foundational visualization library for creating static, animated, and interactive plots. This skill provides guidance on using matplotlib effectively, covering both the pyplot interface (MATLAB-style) and the object-oriented API (Figure/Axes), along with best practices for creating publication-quality visualizations.

When to Use This Skill

This skill should be used when:

• Creating any type of plot or chart (line, scatter, bar, histogram, heatmap, contour, etc.)
• Generating scientific or statistical visualizations
• Customizing plot appearance (colors, styles, labels, legends)
• Creating multi-panel figures with subplots
• Exporting visualizations to various formats (PNG, PDF, SVG, etc.)
• Building interactive plots or animations
• Working with 3D visualizations
• Integrating plots into Jupyter notebooks or GUI applications

Setup

For project work, install Matplotlib with uv:

uv add "matplotlib==3.11.2" numpy scipy

For notebook interactivity:

uv add "matplotlib==3.11.2" ipympl

Then enable the widget backend in Jupyter with %matplotlib widget or %matplotlib ipympl.

Targets Matplotlib 3.11.2 (Python 3.11+), reviewed 2026-10-01. The bundled

scripts and representative examples were executed using Agg and PNG/PDF/SVG output.

GUI windows, Jupyter widgets, and external LaTeX are environment-dependent and were

not exercised. Fragment examples assume imports and named data; adapt and validate

them before use. Check the [3.11 API changes](https://matplotlib.org/stable/api/prev_api_changes/api_changes_3.11.0.html)

when migrating older code: use tick_labels and orientation for box plots,

mpl.colormaps[name] for colormaps, and label contour lines rather than contourf.

File output needs no GUI. Use MPLBACKEND=Agg for batch scripts, or select Agg before

importing pyplot. Interactive output requires an installed GUI toolkit such as

PySide6 (QtAgg) or working Tk (TkAgg); plt.ioff() does not remove GUI thread

requirements. See [backends](https://matplotlib.org/stable/users/explain/figure/backends.html).

Core Concepts

The Matplotlib Hierarchy

Matplotlib uses a hierarchical structure of objects:

1. Figure - The top-level container for all plot elements

2. Axes - The actual plotting area where data is displayed (one Figure can contain multiple Axes)

3. Artist - Everything visible on the figure (lines, text, ticks, etc.)

4. Axis - The number line objects (x-axis, y-axis) that handle ticks and labels

Two Interfaces

1. pyplot Interface (Implicit, MATLAB-style)

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.ylabel('some numbers')
plt.show()

• Convenient for quick, simple plots
• Maintains state automatically
• Good for interactive work and simple scripts

2. Object-Oriented Interface (Explicit)

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.plot([1, 2, 3, 4])
ax.set_ylabel('some numbers')
plt.show()

• Recommended for most use cases
• More explicit control over figure and axes
• Better for complex figures with multiple subplots
• Easier to maintain and debug

Common Workflows

1. Basic Plot Creation

Single plot workflow:

import matplotlib.pyplot as plt
import numpy as np

# Create figure and axes (OO interface - RECOMMENDED)
fig, ax = plt.subplots(figsize=(10, 6))

# Generate and plot data
x = np.linspace(0, 2*np.pi, 100)
ax.plot(x, np.sin(x), label='sin(x)')
ax.plot(x, np.cos(x), label='cos(x)')

# Customize
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.set_title('Trigonometric Functions')
ax.legend()
ax.grid(True, alpha=0.3)

# Save and/or display
fig.savefig('plot.png', dpi=300, bbox_inches='tight')
plt.show()

2. Multiple Subplots

Creating subplot layouts:

# Method 1: Regular grid
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
axes[0, 0].plot(x, y1)
axes[0, 1].scatter(x, y2)
axes[1, 0].bar(categories, values)
axes[1, 1].hist(data, bins=30)

# Method 2: Mosaic layout (more flexible)
fig, axes = plt.subplot_mosaic([['left', 'right_top'],
                                 ['left', 'right_bottom']],
                                figsize=(10, 8))
axes['left'].plot(x, y)
axes['right_top'].scatter(x, y)
axes['right_bottom'].hist(data)

# Method 3: GridSpec (maximum control)
from matplotlib.gridspec import GridSpec
fig = plt.figure(figsize=(12, 8))
gs = GridSpec(3, 3, figure=fig)
ax1 = fig.add_subplot(gs[0, :])  # Top row, all columns
ax2 = fig.add_subplot(gs[1:, 0])  # Bottom two rows, first column
ax3 = fig.add_subplot(gs[1:, 1:])  # Bottom two rows, last two columns

3. Plot Types and Use Cases

Line plots - Time series, continuous data, trends

ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')

Scatter plots - Relationships between variables, correlations

ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')

Bar charts - Categorical comparisons

ax.bar(categories, values, color='steelblue', edgecolor='black')
# For horizontal bars:
ax.barh(categories, values)

Histograms - Distributions

ax.hist(data, bins=30, edgecolor='black', alpha=0.7)

Heatmaps - Matrix data, correlations

im = ax.imshow(matrix, cmap='viridis', aspect='auto', interpolation='nearest')
plt.colorbar(im, ax=ax)

Contour plots - 3D data on 2D plane

contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)

Box plots - Statistical distributions

ax.boxplot([data1, data2, data3], tick_labels=['A', 'B', 'C'])

Violin plots - Distribution densities

ax.violinplot([data1, data2, data3], positions=[1, 2, 3])

For comprehensive plot type examples and variations, refer to references/plot_types.md.

4. Styling and Customization

Color specification methods:

• Named colors: 'red', 'blue', 'steelblue'
• Hex codes: '#FF5733'
• RGB tuples: (0.1, 0.2, 0.3)
• Colormaps: cmap='viridis', cmap='plasma', cmap='coolwarm'

Using style sheets:

plt.style.use('seaborn-v0_8-darkgrid')  # Apply predefined style
# Available styles: 'ggplot', 'bmh', 'fivethirtyeight', etc.
print(plt.style.available)  # List all available styles

Customizing with rcParams:

plt.rcParams['font.size'] = 12
plt.rcParams['axes.labelsize'] = 14
plt.rcParams['axes.titlesize'] = 16
plt.rcParams['xtick.labelsize'] = 10
plt.rcParams['ytick.labelsize'] = 10
plt.rcParams['legend.fontsize'] = 12
plt.rcParams['figure.titlesize'] = 18

Text and annotations:

ax.text(x, y, 'annotation', fontsize=12, ha='center')
ax.annotate('important point', xy=(x, y), xytext=(x+1, y+1),
            arrowprops=dict(arrowstyle='->', color='red'))

For detailed styling options and colormap guidelines, see references/styling_guide.md.

5. Saving Figures

Export to various formats:

# High-resolution PNG for presentations/papers
fig.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')

# Vector format for publications (scalable)
fig.savefig('figure.pdf', bbox_inches='tight')
fig.savefig('figure.svg', bbox_inches='tight')

# Transparent background
fig.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)

Important parameters:

• dpi: Raster pixels per inch; choose from required pixel size and final print size.
• bbox_inches='tight': Crops to artist bounds, changing final physical/pixel dimensions.
• facecolor='white': Ensures white background (useful for transparent themes)
• transparent=True: Makes axes/figure backgrounds transparent; explicit facecolors can override this.

For a fixed-size figure, use constrained layout and omit tight cropping (also set

savefig.bbox=None in an mpl.rc_context if a style sets it). PNG dimensions are

approximately figsize * dpi; PDF/SVG remain vector except images and rasterized

artists. DPI does not add information to source image data. Save with fig.savefig

before show, then plt.close(fig) in batch loops. Inspect the actual exported

file at its final size for clipped labels, missing glyphs, contrast, and readable

legends. See [savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html).

6. Working with 3D Plots

fig = plt.figure(figsize=(10, 8))
ax = fig.add_subplot(111, projection='3d')

# Surface plot
ax.plot_surface(X, Y, Z, cmap='viridis')

# 3D scatter
ax.scatter(x, y, z, c=colors, marker='o')

# 3D line plot
ax.plot(x, y, z, linewidth=2)

# Labels
ax.set_xlabel('X Label')
ax.set_ylabel('Y Label')
ax.set_zlabel('Z Label')

Best Practices

1. Interface Selection

• Use the object-oriented interface (fig, ax = plt.subplots()) for production code
• Reserve pyplot interface for quick interactive exploration only
• Always create figures explicitly rather than relying on implicit s

… (full content is in the download package)