Troubleshooting Guide

Common issues and solutions when using PlotSmith.

Installation Issues

Issue: Import errors or missing dependencies

Solution: Ensure all dependencies are installed:

pip install plotsmith[all]

Issue: Python version compatibility

Solution: PlotSmith requires Python 3.12+. Check your Python version:

python --version

Plotting Issues

Issue: Plots not displaying or saving

Solution: Ensure matplotlib backend is set correctly:

import matplotlib
matplotlib.use('Agg')  # For non-interactive backends
# or
matplotlib.use('TkAgg')  # For GUI backends

Issue: Empty plots or no data visible

Solution: Check that your data is not empty and has valid values:

import pandas as pd
import numpy as np

# Check data
print(data.head())
print(data.info())
print(data.isna().sum())

Issue: “Column not found” errors

Solution: Verify column names match exactly (case-sensitive):

# Check available columns
print(df.columns.tolist())

# Use exact column names
plot_scatter(df, x='exact_column_name', y='another_column')

Data Validation Issues

Issue: “Mismatched lengths” errors

Solution: Ensure all arrays/Series have the same length:

# Check lengths
print(len(x), len(y))

# Align data if needed
common_index = x.index.intersection(y.index)
x_aligned = x.loc[common_index]
y_aligned = y.loc[common_index]

Issue: NaN values causing problems

Solution: Handle NaN values before plotting:

# Remove NaN values
data_clean = data.dropna()

# Or fill NaN values
data_filled = data.fillna(0)

Issue: Empty data errors

Solution: Check for empty data before plotting:

if len(data) == 0:
    print("Warning: Data is empty")
else:
    fig, ax = plot_timeseries(data)

Type Errors

Issue: “TypeError: data must be pandas Series or DataFrame”

Solution: Convert your data to the correct type:

# Convert list to Series
data = pd.Series([1, 2, 3])

# Convert numpy array to Series
data = pd.Series(array_data, index=pd.date_range('2020-01-01', periods=len(array_data)))

Issue: Type checking errors with mypy

Solution: PlotSmith uses type hints. Ensure you’re using compatible types:

from plotsmith import plot_timeseries
import pandas as pd

# Correct: pandas Series
data: pd.Series = pd.Series([1, 2, 3])
fig, ax = plot_timeseries(data)

Performance Issues

Issue: Slow plotting with large datasets

Solution: - Use data sampling for very large datasets - Consider using vectorized operations - Close figures explicitly to free memory

# Sample large data
if len(data) > 10000:
    data_sample = data.sample(1000)
    fig, ax = plot_timeseries(data_sample)
else:
    fig, ax = plot_timeseries(data)

# Always close figures
plt.close(fig)

Styling Issues

Issue: Styling not applied correctly

Solution: Ensure you’re calling styling functions after creating the plot:

from plotsmith import plot_timeseries, minimal_axes

fig, ax = plot_timeseries(data)
minimal_axes(ax)  # Apply styling after plot creation

Issue: Fonts not displaying correctly

Solution: Ensure matplotlib can find the fonts:

import matplotlib
print(matplotlib.get_configdir())
# Check font cache: matplotlib.font_manager._rebuild()

CI/CD Issues

Issue: Tests failing in CI

Solution: - Use non-interactive backend: matplotlib.use(‘Agg’) - Ensure all dependencies are installed - Check Python version compatibility

Issue: Coverage below threshold

Solution: Add tests for uncovered code paths:

pytest --cov=plotsmith --cov-report=html
# Review htmlcov/index.html for coverage gaps

Getting Help

If you encounter issues not covered here:

  1. Check Documentation: Review the full documentation

  2. Search Issues: Check GitHub issues for similar problems

  3. Create Issue: Open a new issue with: - Minimal reproducible example - Error messages - Python and PlotSmith versions - Operating system

Example Issue Template:

import pandas as pd
from plotsmith import plot_timeseries

# Your code here
data = pd.Series([1, 2, 3])
fig, ax = plot_timeseries(data)  # Error occurs here