# Matplotlib Common Issues and Solutions

Troubleshooting guide for frequently encountered matplotlib problems.

## 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. Try different backends
matplotlib.use('TkAgg')  # or 'Qt5Agg', 'MacOSX'
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

# Or turn off interactive mode
plt.ioff()
```

### 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(constrained_layout=True)

# 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: Save with bbox_inches='tight'
plt.savefig('figure.png', bbox_inches='tight')

# Solution 5: Rotate long tick labels
ax.set_xticklabels(labels, 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(constrained_layout=True)
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, constrained_layout=True)

# 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: Compress PNG
plt.savefig('figure.png', dpi=300, 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)  # Keep every 10th point

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

# Solution 3: Use line simplification
ax.plot(x, y)
for line in ax.get_lines():
    line.set_rasterized(True)

# 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: Rebuild font cache
import matplotlib.font_manager
matplotlib.font_manager._rebuild()

# Solution 3: Suppress warnings
import warnings
warnings.filterwarnings("ignore", category=UserWarning)

# Solution 4: Specify fallback fonts
plt.rcParams['font.sans-serif'] = ['Arial', 'DejaVu Sans', 'sans-serif']
```

### 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(constrained_layout=True)
```

## 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
norm = mcolors.Normalize(vmin=data.min(), vmax=data.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)  # colors should have same length as x, y

# 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
# Add _r suffix to reverse any colormap
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:** ValueError when using log scale with data ≤ 0

**Solutions:**
```python
# Solution 1: Filter out non-positive values
mask = (data > 0)
ax.plot(x[mask], data[mask])
ax.set_yscale('log')

# Solution 2: Use symlog for data with positive and negative values
ax.set_yscale('symlog')

# Solution 3: Add small offset
ax.plot(x, data + 1e-10)
ax.set_yscale('log')
```

### 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', ncol=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(ncol=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
from mpl_toolkits.mplot3d import Axes3D

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
# Solution 1: Use interpolation
ax.imshow(img, interpolation='bilinear')
# Options: 'nearest', 'bilinear', 'bicubic', 'spline16', 'spline36', etc.

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

# Solution 3: Use vector format if appropriate
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(constrained_layout=True)
   ```

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. **Use appropriate DPI** - 300 for print, 150 for web
   ```python
   plt.savefig('figure.png', dpi=300)
   ```

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