Quick Start Guide

Get your first chart rendered in under a minute.

Step 1: Install

pip install clean-charts

Step 2: Your First Chart

Every chart function works the same way — pass a DataFrame and optional styling parameters:

import pandas as pd
import clean_charts as cc

df = pd.DataFrame({
    "Response": ["Strongly Agree", "Agree", "Neutral", "Disagree", "Strongly Disagree"],
    "Count": [420, 310, 180, 60, 30],
})

cc.plot_barh_chart(
    data=df,
    title="Customer Satisfaction Survey",
    subtitle="Q2 2024 Results",
    value_suffix=" resp"
)

This displays a publication-quality horizontal bar chart inline. No configuration files, no theme setup — it just works.

Step 3: Save to File

Pass output_path to export as PNG, JPG, PDF, or SVG:

cc.plot_barh_chart(
    data=df,
    title="Customer Satisfaction Survey",
    output_path="survey_results.png"
)

Step 4: Use Built-in Sample Data

Every function ships with sample data. Call without data= to see a demo:

cc.plot_time_series(title="Market Trends")
cc.plot_donut_chart(title="Revenue Breakdown")
cc.plot_dumbbell_chart(title="Year-over-Year Change")

Step 5: Control Dimensions

Use aspect_ratio for semantic sizing, or width/height for pixel-exact control:

# Semantic
cc.plot_barh_chart(data=df, aspect_ratio="landscape")

# Pixel-exact
cc.plot_barh_chart(data=df, width=1200, height=600)

Available ratios: "square", "landscape", "vertical", "1:1", "2:1", "1:2"

What’s Next?