# 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).
