matplotlib

Files (7)

• SKILL.md
• api_reference.md · references/
• common_issues.md · references/
• plot_types.md · references/
• styling_guide.md · references/
• plot_template.py · scripts/
• style_configurator.py · scripts/

SKILL.md (first lines)

# 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:

```bash
uv add "matplotlib==3.11.2" numpy scipy
```

For notebook interactivity:

```bash
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)**
```python
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)**
```python
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:**
```python
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:**
```python

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills