/matplotlib

name: matplotlib
description: 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.
allowed-tools: Read Write Bash
license: https://github.com/matplotlib/matplotlib/tree/main/LICENSE
compatibility: Requires Python 3.10+ and Matplotlib 3.10.x. Use `uv add matplotlib` in projects; interactive Jupyter widgets require `ipympl`.
metadata:
  version: "1.2"
  skill-author: K-Dense Inc.

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:

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='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. Stylin