Skip to content

K-Dense-AI/scientific-agent-skills / skills/matplotlib

matplotlib

Verified

Creates and customizes scientific plots with Matplotlib. Used for fine-grained control over plot elements, novel plot types, and 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.

FileKindSize
SKILL.mdskill md16.2 KB
references/api_reference.mdmarkdown11.6 KB
references/common_issues.mdmarkdown14.8 KB
references/plot_types.mdmarkdown14.5 KB
references/styling_guide.mdmarkdown15.7 KB
scripts/plot_template.pyscript12.4 KB
scripts/style_configurator.pyscript13.9 KB

references/common_issues.md

View on GitHub
# Matplotlib Common Issues and Solutions

Targets Matplotlib 3.11.2. Snippets illustrate individual fixes and assume imports, a figure, and suitable data unless shown. Apply alternatives separately; do not combine layout engines or run notebook magics as Python scripts.

## Display and Backend Issues

### Issue: Plots Not Showing

**Problem:** `plt.show()` doesn't display anything

**Solutions:**
```python
# 1. Check if backend is properly set (for interactive use)
import matplotlib
print(matplotlib.get_backend())

# 2. Select an installed GUI backend before importing pyplot
matplotlib.use('TkAgg')  # or 'QtAgg', 'MacOSX'; requires the corresponding GUI toolkit
import matplotlib.pyplot as plt

# 3. In Jupyter notebooks, use magic command
%matplotlib inline  # Static images
# or
%matplotlib widget  # Interactive plots

# 4. Ensure plt.show() is called
plt.plot([1, 2, 3])
plt.show()
```

### Issue: "RuntimeError: main thread is not in main loop"

**Problem:** Interactive mode issues with threading

**Solution:**
```python
# Switch to non-interactive backend
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt

# plt.ioff() alone does not make a GUI backend safe in a worker thread.
```

### Issue: Figures Not Updating Interactively

**Problem:** Changes not reflected in interactive windows

**Solution:**
```python
# Enable interactive mode
plt.ion()

# Draw after each change
plt.plot(x, y)
plt.draw()
plt.pause(0.001)  # Brief pause to update display
```

## Layout and Spacing Issues

### Issue: Overlapping Labels and Titles

**Problem:** Labels, titles, or tick labels overlap or get cut off

**Solutions:**
```python
# Solution 1: Constrained layout (RECOMMENDED)
fig, ax = plt.subplots(layout='constrained')

# Solution 2: Tight layout
fig, ax = plt.subplots()
plt.tight_layout()

# Solution 3: Adjust margins manually
plt.subplots_adjust(left=0.15, right=0.95, top=0.95, bottom=0.15)

# Solution 4: Crop the export (changes final dimensions; does not fix overlaps)
plt.savefig('figure.png', bbox_inches='tight')

# Solution 5: Rotate long tick labels
ax.set_xticks(positions, labels)
plt.setp(ax.get_xticklabels(), rotation=45, ha='right')
```

### Issue: Colorbar Affects Subplot Size

**Problem:** Adding colorbar shrinks the plot

**Solution:**
```python
# Solution 1: Use constrained layout
fig, ax = plt.subplots(layout='constrained')
im = ax.imshow(data)
plt.colorbar(im, ax=ax)

# Solution 2: Manually specify colorbar dimensions
from mpl_toolkits.axes_grid1 import make_axes_locatable
divider = make_axes_locatable(ax)
cax = divider.append_axes("right", size="5%", pad=0.05)
plt.colorbar(im, cax=cax)

# Solution 3: For multiple subplots, share colorbar
fig, axes = plt.subplots(1, 3, figsize=(15, 4))
for ax in axes:
    im = ax.imshow(data)
fig.colorbar(im, ax=axes.ravel().tolist(), shrink=0.95)
```

### Issue: Subplots Too Close Together

**Problem:** Multiple subplots overlapping

**Solution:**
```python
# Solution 1: Use constrained_layout
fig, axes = plt.subplots(2, 2, layout='constrained')

# Solution 2: Adjust spacing with subplots_adjust
fig, axes = plt.subplots(2, 2)
plt.subplots_adjust(hspace=0.4, wspace=0.4)

# Solution 3: Specify spacing in tight_layout
plt.tight_layout(h_pad=2.0, w_pad=2.0)
```

## Memory and Performance Issues

### Issue: Memory Leak with Multiple Figures

**Problem:** Memory usage grows when creating many figures

**Solution:**
```python
# Close figures explicitly
fig, ax = plt.subplots()
ax.plot(x, y)
plt.savefig('plot.png')
plt.close(fig)  # or plt.close('all')

# Clear current figure without closing
plt.clf()

# Clear current axes
plt.cla()
```

### Issue: Large File Sizes

**Problem:** Saved figures are too large

**Solutions:**
```python
# Solution 1: Reduce DPI
plt.savefig('figure.png', dpi=150)  # Instead of 300

# Solution 2: Use rasterization for complex plots
ax.plot(x, y, rasterized=True)

# Solution 3: Use vector format for simple plots
plt.savefig('figure.pdf')  # or .svg

# Solution 4: Pass PNG compression options through Pillow
fig.savefig('figure.png', dpi=300, pil_kwargs={'optimize': True})
```

### Issue: Slow Plotting with Large Datasets

**Problem:** Plotting takes too long with many points

**Solutions:**
```python
# Solution 1: Downsample data
from scipy.signal import decimate
y_downsampled = decimate(y, 10)  # Anti-alias filtering, then decimation
ax.plot(x[::10], y_downsampled)  # Assumes evenly sampled x; inspect edge effects

# Solution 2: Use rasterization
ax.plot(x, y, rasterized=True)

# Solution 3: Simplify paths in display coordinates; check that peaks survive
with plt.rc_context({'path.simplify': True, 'path.simplify_threshold': 0.1}):
    fig, ax = plt.subplots()
    ax.plot(x, y)
    fig.savefig('simplified.png')

# Solution 4: For scatter plots, consider hexbin or 2d histogram
ax.hexbin(x, y, gridsize=50, cmap='viridis')
```

## Font and Text Issues

### Issue: Font Warnings

**Problem:** "findfont: Font family [...] not found"

**Solutions:**
```python
# Solution 1: Use available fonts
from matplotlib.font_manager import findfont, FontProperties
print(findfont(FontProperties(family=['sans-serif'])))

# Solution 2: Check Matplotlib's cache directory, then restart Python
import matplotlib
print(matplotlib.get_cachedir())

# Solution 3: Specify installed fallback fonts; missing-glyph warnings matter
plt.rcParams['font.sans-serif'] = ['Arial', 'DejaVu Sans']
```

### Issue: LaTeX Rendering Errors

**Problem:** Math text not rendering correctly

**Solutions:**
```python
# Solution 1: Use raw strings with r prefix
ax.set_xlabel(r'$\alpha$')  # Not '\alpha'

# Solution 2: Escape backslashes in regular strings
ax.set_xlabel('$\\alpha$')

# Solution 3: Disable LaTeX if not installed
plt.rcParams['text.usetex'] = False

# Solution 4: Use mathtext instead of full LaTeX
# Mathtext is always available, no LaTeX installation needed
ax.text(x, y, r'$\int_0^\infty e^{-x} dx$')
```

### Issue: Text Cut Off or Outside Figure

**Problem:** Labels or annotations appear outside figure bounds

**Solutions:**
```python
# Solution 1: Use bbox_inches='tight'
plt.savefig('figure.png', bbox_inches='tight')

# Solution 2: Adjust figure bounds
plt.subplots_adjust(left=0.15, right=0.85, top=0.85, bottom=0.15)

# Solution 3: Clip text to axes
ax.text(x, y, 'text', clip_on=True)

# Solution 4: Use constrained_layout
fig, ax = plt.subplots(layout='constrained')
```

## Color and Colormap Issues

### Issue: Colorbar Not Matching Plot

**Problem:** Colorbar shows different range than data

**Solution:**
```python
# Explicitly set vmin and vmax
im = ax.imshow(data, vmin=0, vmax=1, cmap='viridis')
plt.colorbar(im, ax=ax)

# Or use the same norm for multiple plots
import matplotlib.colors as mcolors
# Both panels must have the same physical quantity/units. Exclude missing values.
combined = np.concatenate([np.asarray(data1).ravel(), np.asarray(data2).ravel()])
finite = combined[np.isfinite(combined)]
if finite.size == 0:
    raise ValueError('No finite values for a shared color scale')
norm = mcolors.Normalize(vmin=finite.min(), vmax=finite.max())
im1 = ax1.imshow(data1, norm=norm, cmap='viridis')
im2 = ax2.imshow(data2, norm=norm, cmap='viridis')
```

### Issue: Colors Look Wrong

**Problem:** Unexpected colors in plots

**Solutions:**
```python
# Solution 1: Check color specification format
ax.plot(x, y, color='blue')  # Correct
ax.plot(x, y, color=(0, 0, 1))  # Correct RGB
ax.plot(x, y, color='#0000FF')  # Correct hex

# Solution 2: Verify colormap exists
print(plt.colormaps())  # List available colormaps

# Solution 3: For scatter plots, ensure c shape matches
ax.scatter(x, y, c=colors)  # Numeric colors: one value per point; uniform RGB goes in color=(r, g, b)

# Solution 4: Check if alpha is set correctly
ax.plot(x, y, alpha=1.0)  # 0=transparent, 1=opaque
```

### Issue: Reversed Colormap

**Problem:** Colormap direction is backwards

**Solution:**
```python
# Built-in reversed names have _r; for a custom map use cmap.reversed()
ax.imshow(data, cmap='viridis_r')
```

## Axis and Scale Issues

### Issue: Axis Limits Not Working

**Problem:** `set_xlim` or `set_ylim` not taking effect

**Solutions:**
```python
# Solution 1: Set after plotting
ax.plot(x, y)
ax.set_xlim(0, 10)
ax.set_ylim(-1, 1)

# Solution 2: Disable autoscaling
ax.autoscale(False)
ax.set_xlim(0, 10)

# Solution 3: Use axis method
ax.axis([xmin, xmax, ymin, ymax])
```

### Issue: Log Scale with Zero or Negative Values

**Problem:** Nonpositive observations disappear or are clipped on a log scale

**Solutions:**
```python
# Solution 1: Explicitly mask invalid/nonpositive points, preserving line gaps
masked = np.ma.masked_where(~np.isfinite(data) | (data <= 0), data)
print(f'Excluded {np.ma.count_masked(masked)} points from the log plot')
ax.plot(x, masked)
ax.set_yscale('log', nonpositive='mask')

# Solution 2: Use symlog for data with positive and negative values
ax.set_yscale('symlog', linthresh=1)  # Choose/document threshold in data units
# Do not add an arbitrary epsilon: it changes values and can hide zeros/censoring.
```

### Issue: Dates Not Displaying Correctly

**Problem:** Date axis shows numbers instead of dates

**Solution:**
```python
import matplotlib.dates as mdates
import pandas as pd

# Convert to datetime if needed
dates = pd.to_datetime(date_strings)

ax.plot(dates, values)

# Format date axis
ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y-%m-%d'))
ax.xaxis.set_major_locator(mdates.DayLocator(interval=7))
plt.xticks(rotation=45)
```

## Legend Issues

### Issue: Legend Covers Data

**Problem:** Legend obscures important parts of plot

**Solutions:**
```python
# Solution 1: Use 'best' location
ax.legend(loc='best')

# Solution 2: Place outside plot area
ax.legend(bbox_to_anchor=(1.05, 1), loc='upper left')

# Solution 3: Make legend semi-transparent
ax.legend(framealpha=0.7)

# Solution 4: Put legend below plot
ax.legend(bbox_to_anchor=(0.5, -0.15), loc='upper center', ncols=3)
```

### Issue: Too Many Items in Legend

**Problem:** Legend is cluttered with many entries

**Solutions:**
```python
# Solution 1: Only label selected items
for i, (x, y) in enumerate(data):
    label = f'Data {i}' if i % 5 == 0 else None
    ax.plot(x, y, label=label)

# Solution 2: Use multiple columns
ax.legend(ncols=3)

# Solution 3: Create custom legend with fewer entries
from matplotlib.lines import Line2D
custom_lines = [Line2D([0], [0], color='r'),
                Line2D([0], [0], color='b')]
ax.legend(custom_lines, ['Category A', 'Category B'])

# Solution 4: Use separate legend figure
fig_leg = plt.figure(figsize=(3, 2))
ax_leg = fig_leg.add_subplot(111)
ax_leg.legend(*ax.get_legend_handles_labels(), loc='center')
ax_leg.axis('off')
```

## 3D Plot Issues

### Issue: 3D Plots Look Flat

**Problem:** Difficult to perceive depth in 3D plots

**Solutions:**
```python
# Solution 1: Adjust viewing angle
ax.view_init(elev=30, azim=45)

# Solution 2: Add gridlines
ax.grid(True)

# Solution 3: Use color for depth
scatter = ax.scatter(x, y, z, c=z, cmap='viridis')

# Solution 4: Rotate interactively (if using interactive backend)
# User can click and drag to rotate
```

### Issue: 3D Axis Labels Cut Off

**Problem:** 3D axis labels appear outside figure

**Solution:**
```python
fig = plt.figure(figsize=(10, 8))
ax = fig.add_subplot(111, projection='3d')
ax.plot_surface(X, Y, Z)

# Add padding
fig.tight_layout(pad=3.0)

# Or save with tight bounding box
plt.savefig('3d_plot.png', bbox_inches='tight', pad_inches=0.5)
```

## Image and Colorbar Issues

### Issue: Images Appear Flipped

**Problem:** Image orientation is wrong

**Solution:**
```python
# Set origin parameter
ax.imshow(img, origin='lower')  # or 'upper' (default)

# Or flip array
ax.imshow(np.flipud(img))
```

### Issue: Images Look Pixelated

**Problem:** Image appears blocky when zoomed

**Solutions:**
```python
# For quantitative pixel/cell data preserve the sampling grid
ax.imshow(img, interpolation='nearest')
# Optional display smoothing (not new measurement information)
ax.imshow(img, interpolation='bilinear')
# Options: 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', etc.

# Solution 2: Increase DPI when saving
plt.savefig('figure.png', dpi=300)

# PDF/SVG retain imshow pixels as raster images; they do not recover detail
plt.savefig('figure.pdf')
```

## Common Errors and Fixes

### "TypeError: 'AxesSubplot' object is not subscriptable"

**Problem:** Trying to index single axes
```python
# Wrong
fig, ax = plt.subplots()
ax[0].plot(x, y)  # Error!

# Correct
fig, ax = plt.subplots()
ax.plot(x, y)
```

### "ValueError: x and y must have same first dimension"

**Problem:** Data arrays have mismatched lengths
```python
# Check shapes
print(f"x shape: {x.shape}, y shape: {y.shape}")

# Ensure they match
assert len(x) == len(y), "x and y must have same length"
```

### "AttributeError: 'numpy.ndarray' object has no attribute 'plot'"

**Problem:** Calling plot on array instead of axes
```python
# Wrong
data.plot(x, y)

# Correct
ax.plot(x, y)
# or for pandas
data.plot(ax=ax)
```

## Best Practices to Avoid Issues

1. **Always use the OO interface** - Avoid pyplot state machine
   ```python
   fig, ax = plt.subplots()  # Good
   ax.plot(x, y)
   ```

2. **Use constrained_layout** - Prevents overlap issues
   ```python
   fig, ax = plt.subplots(layout='constrained')
   ```

3. **Close figures explicitly** - Prevents memory leaks
   ```python
   plt.close(fig)
   ```

4. **Set figure size at creation** - Better than resizing later
   ```python
   fig, ax = plt.subplots(figsize=(10, 6))
   ```

5. **Use raw strings for math text** - Avoids escape issues
   ```python
   ax.set_xlabel(r'$\alpha$')
   ```

6. **Check data shapes before plotting** - Catch size mismatches early
   ```python
   assert len(x) == len(y)
   ```

7. **Choose output size and DPI together** - follow the destination requirements
   ```python
   plt.savefig('figure.png', dpi=300)
   ```

8. **Test with different backends** - If display issues occur
   ```python
   import matplotlib
   matplotlib.use('TkAgg')
   ```

## Current API checks

- `fig.get_size_inches()` reads size; there is no public `fig.figsize` attribute.
- `grid.alpha` is the rcParam, not `axes.grid.alpha`.
- 3.11 removes `boxplot(labels=...)` and `matplotlib.cm.get_cmap`; use
  `tick_labels=...` and `matplotlib.colormaps[name]`. Use `orientation` rather than
  deprecated `vert` for box/violin plots.
- In 3.11, `plt.subplots(num=existing_number)` requires `clear=True` to reuse the
  figure by clearing it. To add to an existing Figure, use `fig.subplots(...)`.
- Keep legend handles and labels both positional or both keyword arguments.
- Prefer `cmap.with_extremes(bad='gray')` to pending-deprecated `set_bad`.

Sources: [API changes](https://matplotlib.org/stable/api/prev_api_changes/api_changes_3.11.0.html),
[savefig](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html),
[performance](https://matplotlib.org/stable/users/explain/artists/performance.html),
[constrained layout](https://matplotlib.org/stable/users/explain/axes/constrainedlayout_guide.html).
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 195kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 195kUpdated Claude CodeCodexVerifiedInstall