matplotlib
Low-level plotting library for full customization. Use when you need fine-grained control over every plot element, creating novel plot types, or integrating with specific scientific workflows. Export to PNG/PDF/SVG for publication. For quick statistical plots use seaborn; for interactive plots use plotly; for publication-ready multi-panel figures with journal styling, use scientific-visualization.
Install this skill
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.
npx skills add KalarisLabs/research-agent-skills --skill matplotlibuvx research-agent-skills install matplotlibDocumentation & Instructions
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
For notebook interactivity:
uv add matplotlib ipympl
Then enable the widget backend in Jupyter with %matplotlib widget or %matplotlib ipympl.
Matplotlib 3.10 requires Python 3.10+ and NumPy 1.23+. Non-interactive file output works through backends such as Agg, PDF, and SVG. For GUI windows, Matplotlib auto-selects an available backend; if TkAgg fails in a uv-managed Python, update uv and Python builds with uv self update and uv python upgrade --reinstall, or install a Qt backend with uv add pyside6.
Core Concepts
The Matplotlib Hierarchy
Matplotlib uses a hierarchical structure of objects:
- Figure - The top-level container for all plot elements
- Axes - The actual plotting area where data is displayed (one Figure can contain multiple Axes)
- Artist - Everything visible on the figure (lines, text, ticks, etc.)
- 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='coolwarm', aspect='auto')
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: Resolution (300 for publications, 150 for web, 72 for screen)bbox_inches='tight': Removes excess whitespacefacecolor='white': Ensures white background (useful for transparent themes)transparent=True: Transparent background
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 state
2. Figure Size and DPI
- Set figsize at creation:
fig, ax = plt.subplots(figsize=(10, 6)) - Use appropriate DPI for output medium:
- Screen/notebook: 72-100 dpi
- Web: 150 dpi
- Print/publications: 300 dpi
3. Layout Management
- Use
constrained_layout=Trueortight_layout()to prevent overlapping elements fig, ax = plt.subplots(constrained_layout=True)is recommended for automatic spacing
4. Colormap Selection
- Sequential (viridis, plasma, inferno): Ordered data with consistent progression
- Diverging (coolwarm, RdBu): Data with meaningful center point (e.g., zero)
- Qualitative (tab10, Set3): Categorical/nominal data
- Avoid rainbow colormaps (jet) - they are not perceptually uniform
5. Accessibility
- Use colorblind-friendly colormaps (viridis, cividis)
- Add patterns/hatching for bar charts in addition to colors
- Ensure sufficient contrast between elements
- Include descriptive labels and legends
6. Performance
- For large datasets, use
rasterized=Truein plot calls to reduce file size - Use appropriate data reduction before plotting (e.g., downsample dense time series)
- For animations, use blitting for better performance
7. Code Organization
# Good practice: Clear structure
def create_analysis_plot(data, title):
"""Create standardized analysis plot."""
fig, ax = plt.subplots(figsize=(10, 6), constrained_layout=True)
# Plot data
ax.plot(data['x'], data['y'], linewidth=2)
# Customize
ax.set_xlabel('X Axis Label', fontsize=12)
ax.set_ylabel('Y Axis Label', fontsize=12)
ax.set_title(title, fontsize=14, fontweight='bold')
ax.grid(True, alpha=0.3)
return fig, ax
# Use the function
fig, ax = create_analysis_plot(my_data, 'My Analysis')
fig.savefig('analysis.png', dpi=300, bbox_inches='tight')
Quick Reference Scripts
This skill includes helper scripts in the scripts/ directory:
plot_template.py
Template script demonstrating various plot types with best practices. Use this as a starting point for creating new visualizations.
Usage:
uv run python scripts/plot_template.py
style_configurator.py
Interactive utility to configure matplotlib style preferences and generate custom style sheets.
Usage:
uv run python scripts/style_configurator.py
Detailed References
For comprehensive information, consult the reference documents:
references/plot_types.md- Complete catalog of plot types with code examples and use casesreferences/styling_guide.md- Detailed styling options, colormaps, and customizationreferences/api_reference.md- Core classes and methods referencereferences/common_issues.md- Troubleshooting guide for common problems
Integration with Other Tools
Matplotlib integrates well with:
- NumPy/Pandas - Direct plotting from arrays and DataFrames
- Seaborn - High-level statistical visualizations built on matplotlib
- Jupyter - Interactive plotting with
%matplotlib inlineor%matplotlib widget - GUI frameworks - Embedding in Tkinter, Qt, wxPython applications
Common Gotchas
- Overlapping elements: Use
constrained_layout=Trueortight_layout() - State confusion: Use OO interface to avoid pyplot state machine issues
- Memory issues with many figures: Close figures explicitly with
plt.close(fig) - Font warnings: Install fonts or suppress warnings with
plt.rcParams['font.sans-serif'] - DPI confusion: Remember that figsize is in inches, not pixels:
pixels = dpi * inches
Additional Resources
- Official documentation: https://matplotlib.org/
- Gallery: https://matplotlib.org/stable/gallery/index.html
- Cheatsheets: https://matplotlib.org/cheatsheets/
- Tutorials: https://matplotlib.org/stable/tutorials/index.html
Agent operating procedure
- Check the environment. Confirm the data source, the message each figure must convey, and the target medium (journal, poster, slides).
- Pin down the inputs. Confirm formats, identifiers and parameters from the data or the user. Ask rather than guess any value that changes the result.
- Run a small version first. Render one figure at final size and check legibility before producing the full set.
- Execute the full task using the instructions and references above.
- Validate the result. Axes, units and error bars are labeled and defined; colours are colour-blind safe; numbers match the underlying data.
- Report. State what was run (versions, commands, parameters), what was checked, and what is still uncertain.
| If this happens | Do this |
|---|---|
| Text is unreadable at final size | Increase font sizes or simplify the panel rather than shrinking it. |
| A function, flag or endpoint in these instructions is missing in the installed version | Check the installed version's own documentation (help(), --help, official docs), adapt, and tell the user. Never invent an API. |
| A required input, identifier or parameter is ambiguous | Ask the user, or state the assumption explicitly before running. |
Integrity rules
- Never fabricate results, parameters, identifiers, citations or statistics. If something cannot be run or verified, say so plainly.
- Never alter data to improve a figure's appearance; apply image adjustments uniformly and disclose them.
- Treat version-specific details here as possibly outdated: confirm them against the official documentation for the installed version.
- Ask before actions that cost money, consume shared GPUs or cloud quota, touch personal or patient data, or cannot be undone.
Related skills
seaborn: Statistical visualization with pandas integration.scientific-visualization: Create and audit truthful, accessible, publication-ready scientific figures with Matplotlib, Seaborn, or Plotly.scientific-schematics: Generates publication-style scientific diagrams as raster PNG images from a natural-language prompt, using Nano Banana 2 via OpenRouter, th…
Trigger Prompts & Evaluation Corpus
These evaluation prompts test that the agent correctly selects matplotlib for relevant tasks and leaves it out for near misses.
Should trigger (3)
- should trigger
“Make me a log-scale scatter plot with a fitted line and save it as a vector PDF.”
expects Uses the matplotlib object-oriented API (fig, ax = plt.subplots) with ax.set_xscale/set_yscale('log'), overlays the fit line, labels axes with units, and saves with fig.savefig('...pdf', bbox_inches='tight'). Does not alter the data, and states which assumptions were made, such as the fit method.
- should trigger
“I'm in Jupyter with a DataFrame `df` from results/rnaseq_counts.csv. I need a 2x2 grid: a volcano plot (log2FC vs -log10 padj) with the significant genes in red, a MA plot, a PCA scatter and a library-size bar chart. The shared x labels overlap, and fig.savefig('fig2.png') gives a cropped legend. Please fix both and export at 300 dpi.”
expects Builds the 2x2 layout with plt.subplots and constrained_layout=True (or tight_layout) to stop the overlap. Fixes the legend cropping with bbox_inches='tight' and saves with dpi=300. Uses a colour-blind-safe palette instead of plain red/green, runs one figure at final size first, and checks that the plotted values match the CSV.
- should trigger
“I have a 3D array of electric potential values on a grid and need a picture that shows the field lines and the equipotential surfaces together, with the arrows scaled by field strength. Nothing off the shelf does exactly this, so I'm expecting to write the drawing code myself.”
expects Recognises this as a custom plot needing low-level control and uses matplotlib, combining contour or contourf with quiver or streamplot, and possibly the 3D toolkit, with the arrow scaling set explicitly. Adds a colorbar with a label and units, picks a perceptually uniform colormap, and verifies the field computation against the data.
Near misses (2)
- near miss
“Show the distribution of gene expression across 5 treatment groups in my pandas DataFrame, with a quick violin plot, split by sex, and an attractive default style.”
expects Should go to seaborn: sns.violinplot with hue='sex' on the DataFrame, using the library's default theme. It does not hand-build the plot from matplotlib primitives.
- near miss
“I'm submitting to Nature. Please review my multi-panel Figure 3 for journal sizing, colour-blind accessibility, how missing data and error bars are displayed, and the export specs for the TIFF and metadata requirements.”
expects Should go to scientific-visualization, which audits the figure against journal requirements, accessibility, uncertainty and missing-data displays, and export planning. It is not a general matplotlib customization task.