matplotlib

# 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

## 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
plt.savefig('plot.png', dpi=300, bbox_inches='tight')
plt.show()
```

### 2. Multiple Subplots

**Creating subplot layouts:**
```python
# 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
```python
ax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')
```

**Scatter plots** - Relationships between variables, correlations
```python
ax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')
```

**Bar charts** - Categorical comparisons
```python
ax.bar(categories, values, color='steelblue', edgecolor='black')
# For horizontal bars:
ax.barh(categories, values)
```

**Histograms** - Distributions
```python
ax.hist(data, bins=30, edgecolor='black', alpha=0.7)
```

**Heatmaps** - Matrix data, correlations
```python
im = ax.imshow(matrix, cmap='coolwarm', aspect='auto')
plt.colorbar(im, ax=ax)
```

**Contour plots** - 3D data on 2D plane
```python
contour = ax.contour(X, Y, Z, levels=10)
ax.clabel(contour, inline=True, fontsize=8)
```

**Box plots** - Statistical distributions
```python
ax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])
```

**Violin plots** - Distribution densities
```python
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:**
```python
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:**
```python
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:**
```python
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:**
```python
# High-resolution PNG for presentations/papers
plt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')

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

# Transparent background
plt.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 whitespace
- `facecolor='white'`: Ensures white background (useful for transparent themes)
- `transparent=True`: Transparent background

### 6. Working with 3D Plots

```python
from mpl_toolkits.mplot3d import Axes3D

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=True` or `tight_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=True` in 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
```python
# 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')
plt.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:**
```bash
python scripts/plot_template.py
```

### `style_configurator.py`
Interactive utility to configure matplotlib style preferences and generate custom style sheets.

**Usage:**
```bash
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 cases
- **`references/styling_guide.md`** - Detailed styling options, colormaps, and customization
- **`references/api_reference.md`** - Core classes and methods reference
- **`references/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 inline` or `%matplotlib widget`
- **GUI frameworks** - Embedding in Tkinter, Qt, wxPython applications

## Common Gotchas

1. **Overlapping elements**: Use `constrained_layout=True` or `tight_layout()`
2. **State confusion**: Use OO interface to avoid pyplot state machine issues
3. **Memory issues with many figures**: Close figures explicitly with `plt.close(fig)`
4. **Font warnings**: Install fonts or suppress warnings with `plt.rcParams['font.sans-serif']`
5. **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

{
  "format": "aiskill/v1",
  "skill": {
    "name": "matplotlib",
    "slug": "matplotlib",
    "version": "1.0.0",
    "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.",
    "category": "Research",
    "tags": [
      "research-science",
      "data-viz",
      "documents"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "HTTPS://GITHUB.COM/MATPLOTLIB/MATPLOTLIB/TREE/MAIN/LICENSE"
  },
  "prompts": {
    "system": "# Matplotlib\r\n\r\n## Overview\r\n\r\nMatplotlib 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.\r\n\r\n## When to Use This Skill\r\n\r\nThis skill should be used when:\r\n- Creating any type of plot or chart (line, scatter, bar, histogram, heatmap, contour, etc.)\r\n- Generating scientific or statistical visualizations\r\n- Customizing plot appearance (colors, styles, labels, legends)\r\n- Creating multi-panel figures with subplots\r\n- Exporting visualizations to various formats (PNG, PDF, SVG, etc.)\r\n- Building interactive plots or animations\r\n- Working with 3D visualizations\r\n- Integrating plots into Jupyter notebooks or GUI applications\r\n\r\n## Core Concepts\r\n\r\n### The Matplotlib Hierarchy\r\n\r\nMatplotlib uses a hierarchical structure of objects:\r\n\r\n1. **Figure** - The top-level container for all plot elements\r\n2. **Axes** - The actual plotting area where data is displayed (one Figure can contain multiple Axes)\r\n3. **Artist** - Everything visible on the figure (lines, text, ticks, etc.)\r\n4. **Axis** - The number line objects (x-axis, y-axis) that handle ticks and labels\r\n\r\n### Two Interfaces\r\n\r\n**1. pyplot Interface (Implicit, MATLAB-style)**\r\n```python\r\nimport matplotlib.pyplot as plt\r\n\r\nplt.plot([1, 2, 3, 4])\r\nplt.ylabel('some numbers')\r\nplt.show()\r\n```\r\n- Convenient for quick, simple plots\r\n- Maintains state automatically\r\n- Good for interactive work and simple scripts\r\n\r\n**2. Object-Oriented Interface (Explicit)**\r\n```python\r\nimport matplotlib.pyplot as plt\r\n\r\nfig, ax = plt.subplots()\r\nax.plot([1, 2, 3, 4])\r\nax.set_ylabel('some numbers')\r\nplt.show()\r\n```\r\n- **Recommended for most use cases**\r\n- More explicit control over figure and axes\r\n- Better for complex figures with multiple subplots\r\n- Easier to maintain and debug\r\n\r\n## Common Workflows\r\n\r\n### 1. Basic Plot Creation\r\n\r\n**Single plot workflow:**\r\n```python\r\nimport matplotlib.pyplot as plt\r\nimport numpy as np\r\n\r\n# Create figure and axes (OO interface - RECOMMENDED)\r\nfig, ax = plt.subplots(figsize=(10, 6))\r\n\r\n# Generate and plot data\r\nx = np.linspace(0, 2*np.pi, 100)\r\nax.plot(x, np.sin(x), label='sin(x)')\r\nax.plot(x, np.cos(x), label='cos(x)')\r\n\r\n# Customize\r\nax.set_xlabel('x')\r\nax.set_ylabel('y')\r\nax.set_title('Trigonometric Functions')\r\nax.legend()\r\nax.grid(True, alpha=0.3)\r\n\r\n# Save and/or display\r\nplt.savefig('plot.png', dpi=300, bbox_inches='tight')\r\nplt.show()\r\n```\r\n\r\n### 2. Multiple Subplots\r\n\r\n**Creating subplot layouts:**\r\n```python\r\n# Method 1: Regular grid\r\nfig, axes = plt.subplots(2, 2, figsize=(12, 10))\r\naxes[0, 0].plot(x, y1)\r\naxes[0, 1].scatter(x, y2)\r\naxes[1, 0].bar(categories, values)\r\naxes[1, 1].hist(data, bins=30)\r\n\r\n# Method 2: Mosaic layout (more flexible)\r\nfig, axes = plt.subplot_mosaic([['left', 'right_top'],\r\n                                 ['left', 'right_bottom']],\r\n                                figsize=(10, 8))\r\naxes['left'].plot(x, y)\r\naxes['right_top'].scatter(x, y)\r\naxes['right_bottom'].hist(data)\r\n\r\n# Method 3: GridSpec (maximum control)\r\nfrom matplotlib.gridspec import GridSpec\r\nfig = plt.figure(figsize=(12, 8))\r\ngs = GridSpec(3, 3, figure=fig)\r\nax1 = fig.add_subplot(gs[0, :])  # Top row, all columns\r\nax2 = fig.add_subplot(gs[1:, 0])  # Bottom two rows, first column\r\nax3 = fig.add_subplot(gs[1:, 1:])  # Bottom two rows, last two columns\r\n```\r\n\r\n### 3. Plot Types and Use Cases\r\n\r\n**Line plots** - Time series, continuous data, trends\r\n```python\r\nax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')\r\n```\r\n\r\n**Scatter plots** - Relationships between variables, correlations\r\n```python\r\nax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')\r\n```\r\n\r\n**Bar charts** - Categorical comparisons\r\n```python\r\nax.bar(categories, values, color='steelblue', edgecolor='black')\r\n# For horizontal bars:\r\nax.barh(categories, values)\r\n```\r\n\r\n**Histograms** - Distributions\r\n```python\r\nax.hist(data, bins=30, edgecolor='black', alpha=0.7)\r\n```\r\n\r\n**Heatmaps** - Matrix data, correlations\r\n```python\r\nim = ax.imshow(matrix, cmap='coolwarm', aspect='auto')\r\nplt.colorbar(im, ax=ax)\r\n```\r\n\r\n**Contour plots** - 3D data on 2D plane\r\n```python\r\ncontour = ax.contour(X, Y, Z, levels=10)\r\nax.clabel(contour, inline=True, fontsize=8)\r\n```\r\n\r\n**Box plots** - Statistical distributions\r\n```python\r\nax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])\r\n```\r\n\r\n**Violin plots** - Distribution densities\r\n```python\r\nax.violinplot([data1, data2, data3], positions=[1, 2, 3])\r\n```\r\n\r\nFor comprehensive plot type examples and variations, refer to `references/plot_types.md`.\r\n\r\n### 4. Styling and Customization\r\n\r\n**Color specification methods:**\r\n- Named colors: `'red'`, `'blue'`, `'steelblue'`\r\n- Hex codes: `'#FF5733'`\r\n- RGB tuples: `(0.1, 0.2, 0.3)`\r\n- Colormaps: `cmap='viridis'`, `cmap='plasma'`, `cmap='coolwarm'`\r\n\r\n**Using style sheets:**\r\n```python\r\nplt.style.use('seaborn-v0_8-darkgrid')  # Apply predefined style\r\n# Available styles: 'ggplot', 'bmh', 'fivethirtyeight', etc.\r\nprint(plt.style.available)  # List all available styles\r\n```\r\n\r\n**Customizing with rcParams:**\r\n```python\r\nplt.rcParams['font.size'] = 12\r\nplt.rcParams['axes.labelsize'] = 14\r\nplt.rcParams['axes.titlesize'] = 16\r\nplt.rcParams['xtick.labelsize'] = 10\r\nplt.rcParams['ytick.labelsize'] = 10\r\nplt.rcParams['legend.fontsize'] = 12\r\nplt.rcParams['figure.titlesize'] = 18\r\n```\r\n\r\n**Text and annotations:**\r\n```python\r\nax.text(x, y, 'annotation', fontsize=12, ha='center')\r\nax.annotate('important point', xy=(x, y), xytext=(x+1, y+1),\r\n            arrowprops=dict(arrowstyle='->', color='red'))\r\n```\r\n\r\nFor detailed styling options and colormap guidelines, see `references/styling_guide.md`.\r\n\r\n### 5. Saving Figures\r\n\r\n**Export to various formats:**\r\n```python\r\n# High-resolution PNG for presentations/papers\r\nplt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')\r\n\r\n# Vector format for publications (scalable)\r\nplt.savefig('figure.pdf', bbox_inches='tight')\r\nplt.savefig('figure.svg', bbox_inches='tight')\r\n\r\n# Transparent background\r\nplt.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)\r\n```\r\n\r\n**Important parameters:**\r\n- `dpi`: Resolution (300 for publications, 150 for web, 72 for screen)\r\n- `bbox_inches='tight'`: Removes excess whitespace\r\n- `facecolor='white'`: Ensures white background (useful for transparent themes)\r\n- `transparent=True`: Transparent background\r\n\r\n### 6. Working with 3D Plots\r\n\r\n```python\r\nfrom mpl_toolkits.mplot3d import Axes3D\r\n\r\nfig = plt.figure(figsize=(10, 8))\r\nax = fig.add_subplot(111, projection='3d')\r\n\r\n# Surface plot\r\nax.plot_surface(X, Y, Z, cmap='viridis')\r\n\r\n# 3D scatter\r\nax.scatter(x, y, z, c=colors, marker='o')\r\n\r\n# 3D line plot\r\nax.plot(x, y, z, linewidth=2)\r\n\r\n# Labels\r\nax.set_xlabel('X Label')\r\nax.set_ylabel('Y Label')\r\nax.set_zlabel('Z Label')\r\n```\r\n\r\n## Best Practices\r\n\r\n### 1. Interface Selection\r\n- **Use the object-oriented interface** (fig, ax = plt.subplots()) for production code\r\n- Reserve pyplot interface for quick interactive exploration only\r\n- Always create figures explicitly rather than relying on implicit state\r\n\r\n### 2. Figure Size and DPI\r\n- Set figsize at creation: `fig, ax = plt.subplots(figsize=(10, 6))`\r\n- Use appropriate DPI for output medium:\r\n  - Screen/notebook: 72-100 dpi\r\n  - Web: 150 dpi\r\n  - Print/publications: 300 dpi\r\n\r\n### 3. Layout Management\r\n- Use `constrained_layout=True` or `tight_layout()` to prevent overlapping elements\r\n- `fig, ax = plt.subplots(constrained_layout=True)` is recommended for automatic spacing\r\n\r\n### 4. Colormap Selection\r\n- **Sequential** (viridis, plasma, inferno): Ordered data with consistent progression\r\n- **Diverging** (coolwarm, RdBu): Data with meaningful center point (e.g., zero)\r\n- **Qualitative** (tab10, Set3): Categorical/nominal data\r\n- Avoid rainbow colormaps (jet) - they are not perceptually uniform\r\n\r\n### 5. Accessibility\r\n- Use colorblind-friendly colormaps (viridis, cividis)\r\n- Add patterns/hatching for bar charts in addition to colors\r\n- Ensure sufficient contrast between elements\r\n- Include descriptive labels and legends\r\n\r\n### 6. Performance\r\n- For large datasets, use `rasterized=True` in plot calls to reduce file size\r\n- Use appropriate data reduction before plotting (e.g., downsample dense time series)\r\n- For animations, use blitting for better performance\r\n\r\n### 7. Code Organization\r\n```python\r\n# Good practice: Clear structure\r\ndef create_analysis_plot(data, title):\r\n    \"\"\"Create standardized analysis plot.\"\"\"\r\n    fig, ax = plt.subplots(figsize=(10, 6), constrained_layout=True)\r\n\r\n    # Plot data\r\n    ax.plot(data['x'], data['y'], linewidth=2)\r\n\r\n    # Customize\r\n    ax.set_xlabel('X Axis Label', fontsize=12)\r\n    ax.set_ylabel('Y Axis Label', fontsize=12)\r\n    ax.set_title(title, fontsize=14, fontweight='bold')\r\n    ax.grid(True, alpha=0.3)\r\n\r\n    return fig, ax\r\n\r\n# Use the function\r\nfig, ax = create_analysis_plot(my_data, 'My Analysis')\r\nplt.savefig('analysis.png', dpi=300, bbox_inches='tight')\r\n```\r\n\r\n## Quick Reference Scripts\r\n\r\nThis skill includes helper scripts in the `scripts/` directory:\r\n\r\n### `plot_template.py`\r\nTemplate script demonstrating various plot types with best practices. Use this as a starting point for creating new visualizations.\r\n\r\n**Usage:**\r\n```bash\r\npython scripts/plot_template.py\r\n```\r\n\r\n### `style_configurator.py`\r\nInteractive utility to configure matplotlib style preferences and generate custom style sheets.\r\n\r\n**Usage:**\r\n```bash\r\npython scripts/style_configurator.py\r\n```\r\n\r\n## Detailed References\r\n\r\nFor comprehensive information, consult the reference documents:\r\n\r\n- **`references/plot_types.md`** - Complete catalog of plot types with code examples and use cases\r\n- **`references/styling_guide.md`** - Detailed styling options, colormaps, and customization\r\n- **`references/api_reference.md`** - Core classes and methods reference\r\n- **`references/common_issues.md`** - Troubleshooting guide for common problems\r\n\r\n## Integration with Other Tools\r\n\r\nMatplotlib integrates well with:\r\n- **NumPy/Pandas** - Direct plotting from arrays and DataFrames\r\n- **Seaborn** - High-level statistical visualizations built on matplotlib\r\n- **Jupyter** - Interactive plotting with `%matplotlib inline` or `%matplotlib widget`\r\n- **GUI frameworks** - Embedding in Tkinter, Qt, wxPython applications\r\n\r\n## Common Gotchas\r\n\r\n1. **Overlapping elements**: Use `constrained_layout=True` or `tight_layout()`\r\n2. **State confusion**: Use OO interface to avoid pyplot state machine issues\r\n3. **Memory issues with many figures**: Close figures explicitly with `plt.close(fig)`\r\n4. **Font warnings**: Install fonts or suppress warnings with `plt.rcParams['font.sans-serif']`\r\n5. **DPI confusion**: Remember that figsize is in inches, not pixels: `pixels = dpi * inches`\r\n\r\n## Additional Resources\r\n\r\n- Official documentation: https://matplotlib.org/\r\n- Gallery: https://matplotlib.org/stable/gallery/index.html\r\n- Cheatsheets: https://matplotlib.org/cheatsheets/\r\n- Tutorials: https://matplotlib.org/stable/tutorials/index.html",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The matplotlib/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/matplotlib",
    "exported_at": "2026-11-03T07:40:51.696Z"
  }
}

format: aiskill/v1
skill:
  name: matplotlib
  slug: matplotlib
  version: 1.0.0
  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.
  category: Research
  tags:
    - research-science
    - data-viz
    - documents
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: HTTPS://GITHUB.COM/MATPLOTLIB/MATPLOTLIB/TREE/MAIN/LICENSE
prompts:
  system: "# Matplotlib\r\n\r\n## Overview\r\n\r\nMatplotlib 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.\r\n\r\n## When to Use This Skill\r\n\r\nThis skill should be used when:\r\n- Creating any type of plot or chart (line, scatter, bar, histogram, heatmap, contour, etc.)\r\n- Generating scientific or statistical visualizations\r\n- Customizing plot appearance (colors, styles, labels, legends)\r\n- Creating multi-panel figures with subplots\r\n- Exporting visualizations to various formats (PNG, PDF, SVG, etc.)\r\n- Building interactive plots or animations\r\n- Working with 3D visualizations\r\n- Integrating plots into Jupyter notebooks or GUI applications\r\n\r\n## Core Concepts\r\n\r\n### The Matplotlib Hierarchy\r\n\r\nMatplotlib uses a hierarchical structure of objects:\r\n\r\n1. **Figure** - The top-level container for all plot elements\r\n2. **Axes** - The actual plotting area where data is displayed (one Figure can contain multiple Axes)\r\n3. **Artist** - Everything visible on the figure (lines, text, ticks, etc.)\r\n4. **Axis** - The number line objects (x-axis, y-axis) that handle ticks and labels\r\n\r\n### Two Interfaces\r\n\r\n**1. pyplot Interface (Implicit, MATLAB-style)**\r\n```python\r\nimport matplotlib.pyplot as plt\r\n\r\nplt.plot([1, 2, 3, 4])\r\nplt.ylabel('some numbers')\r\nplt.show()\r\n```\r\n- Convenient for quick, simple plots\r\n- Maintains state automatically\r\n- Good for interactive work and simple scripts\r\n\r\n**2. Object-Oriented Interface (Explicit)**\r\n```python\r\nimport matplotlib.pyplot as plt\r\n\r\nfig, ax = plt.subplots()\r\nax.plot([1, 2, 3, 4])\r\nax.set_ylabel('some numbers')\r\nplt.show()\r\n```\r\n- **Recommended for most use cases**\r\n- More explicit control over figure and axes\r\n- Better for complex figures with multiple subplots\r\n- Easier to maintain and debug\r\n\r\n## Common Workflows\r\n\r\n### 1. Basic Plot Creation\r\n\r\n**Single plot workflow:**\r\n```python\r\nimport matplotlib.pyplot as plt\r\nimport numpy as np\r\n\r\n# Create figure and axes (OO interface - RECOMMENDED)\r\nfig, ax = plt.subplots(figsize=(10, 6))\r\n\r\n# Generate and plot data\r\nx = np.linspace(0, 2*np.pi, 100)\r\nax.plot(x, np.sin(x), label='sin(x)')\r\nax.plot(x, np.cos(x), label='cos(x)')\r\n\r\n# Customize\r\nax.set_xlabel('x')\r\nax.set_ylabel('y')\r\nax.set_title('Trigonometric Functions')\r\nax.legend()\r\nax.grid(True, alpha=0.3)\r\n\r\n# Save and/or display\r\nplt.savefig('plot.png', dpi=300, bbox_inches='tight')\r\nplt.show()\r\n```\r\n\r\n### 2. Multiple Subplots\r\n\r\n**Creating subplot layouts:**\r\n```python\r\n# Method 1: Regular grid\r\nfig, axes = plt.subplots(2, 2, figsize=(12, 10))\r\naxes[0, 0].plot(x, y1)\r\naxes[0, 1].scatter(x, y2)\r\naxes[1, 0].bar(categories, values)\r\naxes[1, 1].hist(data, bins=30)\r\n\r\n# Method 2: Mosaic layout (more flexible)\r\nfig, axes = plt.subplot_mosaic([['left', 'right_top'],\r\n                                 ['left', 'right_bottom']],\r\n                                figsize=(10, 8))\r\naxes['left'].plot(x, y)\r\naxes['right_top'].scatter(x, y)\r\naxes['right_bottom'].hist(data)\r\n\r\n# Method 3: GridSpec (maximum control)\r\nfrom matplotlib.gridspec import GridSpec\r\nfig = plt.figure(figsize=(12, 8))\r\ngs = GridSpec(3, 3, figure=fig)\r\nax1 = fig.add_subplot(gs[0, :])  # Top row, all columns\r\nax2 = fig.add_subplot(gs[1:, 0])  # Bottom two rows, first column\r\nax3 = fig.add_subplot(gs[1:, 1:])  # Bottom two rows, last two columns\r\n```\r\n\r\n### 3. Plot Types and Use Cases\r\n\r\n**Line plots** - Time series, continuous data, trends\r\n```python\r\nax.plot(x, y, linewidth=2, linestyle='--', marker='o', color='blue')\r\n```\r\n\r\n**Scatter plots** - Relationships between variables, correlations\r\n```python\r\nax.scatter(x, y, s=sizes, c=colors, alpha=0.6, cmap='viridis')\r\n```\r\n\r\n**Bar charts** - Categorical comparisons\r\n```python\r\nax.bar(categories, values, color='steelblue', edgecolor='black')\r\n# For horizontal bars:\r\nax.barh(categories, values)\r\n```\r\n\r\n**Histograms** - Distributions\r\n```python\r\nax.hist(data, bins=30, edgecolor='black', alpha=0.7)\r\n```\r\n\r\n**Heatmaps** - Matrix data, correlations\r\n```python\r\nim = ax.imshow(matrix, cmap='coolwarm', aspect='auto')\r\nplt.colorbar(im, ax=ax)\r\n```\r\n\r\n**Contour plots** - 3D data on 2D plane\r\n```python\r\ncontour = ax.contour(X, Y, Z, levels=10)\r\nax.clabel(contour, inline=True, fontsize=8)\r\n```\r\n\r\n**Box plots** - Statistical distributions\r\n```python\r\nax.boxplot([data1, data2, data3], labels=['A', 'B', 'C'])\r\n```\r\n\r\n**Violin plots** - Distribution densities\r\n```python\r\nax.violinplot([data1, data2, data3], positions=[1, 2, 3])\r\n```\r\n\r\nFor comprehensive plot type examples and variations, refer to `references/plot_types.md`.\r\n\r\n### 4. Styling and Customization\r\n\r\n**Color specification methods:**\r\n- Named colors: `'red'`, `'blue'`, `'steelblue'`\r\n- Hex codes: `'#FF5733'`\r\n- RGB tuples: `(0.1, 0.2, 0.3)`\r\n- Colormaps: `cmap='viridis'`, `cmap='plasma'`, `cmap='coolwarm'`\r\n\r\n**Using style sheets:**\r\n```python\r\nplt.style.use('seaborn-v0_8-darkgrid')  # Apply predefined style\r\n# Available styles: 'ggplot', 'bmh', 'fivethirtyeight', etc.\r\nprint(plt.style.available)  # List all available styles\r\n```\r\n\r\n**Customizing with rcParams:**\r\n```python\r\nplt.rcParams['font.size'] = 12\r\nplt.rcParams['axes.labelsize'] = 14\r\nplt.rcParams['axes.titlesize'] = 16\r\nplt.rcParams['xtick.labelsize'] = 10\r\nplt.rcParams['ytick.labelsize'] = 10\r\nplt.rcParams['legend.fontsize'] = 12\r\nplt.rcParams['figure.titlesize'] = 18\r\n```\r\n\r\n**Text and annotations:**\r\n```python\r\nax.text(x, y, 'annotation', fontsize=12, ha='center')\r\nax.annotate('important point', xy=(x, y), xytext=(x+1, y+1),\r\n            arrowprops=dict(arrowstyle='->', color='red'))\r\n```\r\n\r\nFor detailed styling options and colormap guidelines, see `references/styling_guide.md`.\r\n\r\n### 5. Saving Figures\r\n\r\n**Export to various formats:**\r\n```python\r\n# High-resolution PNG for presentations/papers\r\nplt.savefig('figure.png', dpi=300, bbox_inches='tight', facecolor='white')\r\n\r\n# Vector format for publications (scalable)\r\nplt.savefig('figure.pdf', bbox_inches='tight')\r\nplt.savefig('figure.svg', bbox_inches='tight')\r\n\r\n# Transparent background\r\nplt.savefig('figure.png', dpi=300, bbox_inches='tight', transparent=True)\r\n```\r\n\r\n**Important parameters:**\r\n- `dpi`: Resolution (300 for publications, 150 for web, 72 for screen)\r\n- `bbox_inches='tight'`: Removes excess whitespace\r\n- `facecolor='white'`: Ensures white background (useful for transparent themes)\r\n- `transparent=True`: Transparent background\r\n\r\n### 6. Working with 3D Plots\r\n\r\n```python\r\nfrom mpl_toolkits.mplot3d import Axes3D\r\n\r\nfig = plt.figure(figsize=(10, 8))\r\nax = fig.add_subplot(111, projection='3d')\r\n\r\n# Surface plot\r\nax.plot_surface(X, Y, Z, cmap='viridis')\r\n\r\n# 3D scatter\r\nax.scatter(x, y, z, c=colors, marker='o')\r\n\r\n# 3D line plot\r\nax.plot(x, y, z, linewidth=2)\r\n\r\n# Labels\r\nax.set_xlabel('X Label')\r\nax.set_ylabel('Y Label')\r\nax.set_zlabel('Z Label')\r\n```\r\n\r\n## Best Practices\r\n\r\n### 1. Interface Selection\r\n- **Use the object-oriented interface** (fig, ax = plt.subplots()) for production code\r\n- Reserve pyplot interface for quick interactive exploration only\r\n- Always create figures explicitly rather than relying on implicit state\r\n\r\n### 2. Figure Size and DPI\r\n- Set figsize at creation: `fig, ax = plt.subplots(figsize=(10, 6))`\r\n- Use appropriate DPI for output medium:\r\n  - Screen/notebook: 72-100 dpi\r\n  - Web: 150 dpi\r\n  - Print/publications: 300 dpi\r\n\r\n### 3. Layout Management\r\n- Use `constrained_layout=True` or `tight_layout()` to prevent overlapping elements\r\n- `fig, ax = plt.subplots(constrained_layout=True)` is recommended for automatic spacing\r\n\r\n### 4. Colormap Selection\r\n- **Sequential** (viridis, plasma, inferno): Ordered data with consistent progression\r\n- **Diverging** (coolwarm, RdBu): Data with meaningful center point (e.g., zero)\r\n- **Qualitative** (tab10, Set3): Categorical/nominal data\r\n- Avoid rainbow colormaps (jet) - they are not perceptually uniform\r\n\r\n### 5. Accessibility\r\n- Use colorblind-friendly colormaps (viridis, cividis)\r\n- Add patterns/hatching for bar charts in addition to colors\r\n- Ensure sufficient contrast between elements\r\n- Include descriptive labels and legends\r\n\r\n### 6. Performance\r\n- For large datasets, use `rasterized=True` in plot calls to reduce file size\r\n- Use appropriate data reduction before plotting (e.g., downsample dense time series)\r\n- For animations, use blitting for better performance\r\n\r\n### 7. Code Organization\r\n```python\r\n# Good practice: Clear structure\r\ndef create_analysis_plot(data, title):\r\n    \"\"\"Create standardized analysis plot.\"\"\"\r\n    fig, ax = plt.subplots(figsize=(10, 6), constrained_layout=True)\r\n\r\n    # Plot data\r\n    ax.plot(data['x'], data['y'], linewidth=2)\r\n\r\n    # Customize\r\n    ax.set_xlabel('X Axis Label', fontsize=12)\r\n    ax.set_ylabel('Y Axis Label', fontsize=12)\r\n    ax.set_title(title, fontsize=14, fontweight='bold')\r\n    ax.grid(True, alpha=0.3)\r\n\r\n    return fig, ax\r\n\r\n# Use the function\r\nfig, ax = create_analysis_plot(my_data, 'My Analysis')\r\nplt.savefig('analysis.png', dpi=300, bbox_inches='tight')\r\n```\r\n\r\n## Quick Reference Scripts\r\n\r\nThis skill includes helper scripts in the `scripts/` directory:\r\n\r\n### `plot_template.py`\r\nTemplate script demonstrating various plot types with best practices. Use this as a starting point for creating new visualizations.\r\n\r\n**Usage:**\r\n```bash\r\npython scripts/plot_template.py\r\n```\r\n\r\n### `style_configurator.py`\r\nInteractive utility to configure matplotlib style preferences and generate custom style sheets.\r\n\r\n**Usage:**\r\n```bash\r\npython scripts/style_configurator.py\r\n```\r\n\r\n## Detailed References\r\n\r\nFor comprehensive information, consult the reference documents:\r\n\r\n- **`references/plot_types.md`** - Complete catalog of plot types with code examples and use cases\r\n- **`references/styling_guide.md`** - Detailed styling options, colormaps, and customization\r\n- **`references/api_reference.md`** - Core classes and methods reference\r\n- **`references/common_issues.md`** - Troubleshooting guide for common problems\r\n\r\n## Integration with Other Tools\r\n\r\nMatplotlib integrates well with:\r\n- **NumPy/Pandas** - Direct plotting from arrays and DataFrames\r\n- **Seaborn** - High-level statistical visualizations built on matplotlib\r\n- **Jupyter** - Interactive plotting with `%matplotlib inline` or `%matplotlib widget`\r\n- **GUI frameworks** - Embedding in Tkinter, Qt, wxPython applications\r\n\r\n## Common Gotchas\r\n\r\n1. **Overlapping elements**: Use `constrained_layout=True` or `tight_layout()`\r\n2. **State confusion**: Use OO interface to avoid pyplot state machine issues\r\n3. **Memory issues with many figures**: Close figures explicitly with `plt.close(fig)`\r\n4. **Font warnings**: Install fonts or suppress warnings with `plt.rcParams['font.sans-serif']`\r\n5. **DPI confusion**: Remember that figsize is in inches, not pixels: `pixels = dpi * inches`\r\n\r\n## Additional Resources\r\n\r\n- Official documentation: https://matplotlib.org/\r\n- Gallery: https://matplotlib.org/stable/gallery/index.html\r\n- Cheatsheets: https://matplotlib.org/cheatsheets/\r\n- Tutorials: https://matplotlib.org/stable/tutorials/index.html"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The matplotlib/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/matplotlib
  exported_at: "2026-11-03T07:40:51.696Z"