Clean Charts

Clean Charts is a lightweight Python library for creating beautiful, publication-quality data visualizations inspired by modern editorial styles like The Economist. Go from raw data to presentation-ready charts in a single function call — no styling boilerplate required.

Table of Contents

• ✨ Highlights
• 📦 Installation
• 🚀 Quick Start
• 🎨 Customizing Data & Advanced Usage
• 📖 API Reference
• 🎛️ Global Customization
• 🧪 Examples & Development
• 📄 License

✨ Highlights

📦 Installation

pip install clean-charts

Dependencies (installed automatically): matplotlib ≥ 3.5, pandas ≥ 1.3, numpy ≥ 1.20, Pillow ≥ 8.0, scipy ≥ 1.7.

🚀 Quick Start

1. Grouped Horizontal Bar Chart

Display multiple numeric series side-by-side for each category, with an automatic color gradient and legend.

import pandas as pd
from clean_charts import plot_grouped_barh_chart

df = pd.DataFrame({
    'Fruit': ['Apples', 'Bananas', 'Cherries', 'Dates', 'Elderberries', 'Figs', 'Grapes'],
    '2024': [380, 410, 150, 420, 85,  280, 490],
    '2025': [510, 180, 830, 450, 190, 240, 560],
    '2026': [415, 450, 590, 310, 60,  310, 400]
})

plot_grouped_barh_chart(
    data = df,
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items to optimize supply chain distribution",
    bar_padding=0,
    group_padding=0.3,
    value_suffix = ' Kg'
)

Output:

2. Horizontal Bar Chart

Draw a single-series horizontal bar chart with category labels and value annotations.

import pandas as pd
from clean_charts import plot_barh_chart

df = pd.DataFrame({
    'Category': ['Apples', 'Bananas', 'Cherries', 'Dates', 'Elderberries', 'Figs', 'Grapes', 'Honeydew'],
    'Sales':    [400, 350, 300, 450, 120, 210, 520, 180],
})

plot_barh_chart(
    data=df,
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items to optimize supply chain distribution",
    value_suffix=' Kg',
)

Output:

3. Time-Series Line Chart

Generate a time-series line chart with smooth PCHIP spline curves, right-aligned Y-axis, and smart inline labels.

import pandas as pd
from clean_charts import plot_time_series

df = pd.DataFrame({
    'Dates': pd.date_range("2026-01-01", periods=12, freq="MS"),
    'Apples': [500, 596, 590, 523, 582, 515, 501, 551, 494, 467, 548, 490],
    'Bananas': [350, 339, 349, 200, 328, 359, 403, 390, 459, 390, 373, 437],
    'Elderberries': [160, 118, 118, 124, 179, 126, 117, 115, 157, 114, 120, 127]
})

plot_time_series(
    data=df,
    aspect_ratio='1:1',    
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items to optimize supply chain distribution",
    label_frequency="month", 
    line_labels='name',
    value_suffix=' Kg',
    vlines={"date": "2026-06-15", "color": "#000000", "label": "Policy Change"},
    callouts={"date": "2026-04-01",
              "series": "Bananas",
              "text": "Loss in harvest\ndue to pests"}
)

Output:

4. Donut Chart

Draw a stylized donut chart with automatic label placement that avoids overlaps.

import pandas as pd
from clean_charts import plot_donut_chart

df = pd.DataFrame({
    'Category': ['Apples', 'Bananas', 'Cherries', 'Dates', 'Elderberries', 'Figs', 'Grapes', 'Honeydew'],
    'Sales': [400, 350, 300, 450, 120, 210, 520, 180]
})

plot_donut_chart(
    data=df,
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items to optimize supply chain distribution",
    value_suffix=' kg',
    start_angle=60,
)

Output:

5. Stacked Horizontal Bar Chart

Visualize part-to-whole relationships across categories. Supports raw values or 100 % stacked mode.

import pandas as pd
from clean_charts import plot_stacked_bar_chart

df = pd.DataFrame({
    'Year': ['2021', '2022', '2023', '2024', '2025', '2026'],
    'Apples': [320, 340, 360, 380, 510, 415],
    'Bananas': [390, 400, 405, 410, 180, 450],
    'Cherries': [120, 135, 140, 150, 830, 590]
})

plot_stacked_bar_chart(
    data = df,
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items to optimize supply chain distribution",
    bar_padding=0.5,
    value_suffix=' Kg',
    show_percentages=True,
    bar_labels='value',
    aspect_ratio='1:1',
    scale_text=False
)

Output:

6. Vertical Bar Chart

Draw a single-series vertical bar chart with category labels along the X-axis and value annotations above each bar.

import pandas as pd
from clean_charts import plot_barv_chart

df = pd.DataFrame({
    'Category': ['Apples', 'Bananas', 'Cherries', 'Dates', 'Elderberries', 'Figs', 'Grapes', 'Honeydew'],
    'Sales': [400, 350, 300, 450, 120, 210, 520, 180]
})

plot_barv_chart(
    data=df,
    width=850,
    height=500,
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items to optimize supply chain distribution",
    value_suffix=' Kg',
    bar_padding=0.6
)

Output:

7. Waffle Chart

Visualize survey-style percentage data as 10×10 dot grids — one grid per category. Each filled dot represents 1 percentage point. Long descriptions auto-wrap and the grid scales dynamically to prevent text truncation.

import pandas as pd
from clean_charts import plot_waffle_chart

data = pd.DataFrame({
    "Label": ["Visionaries", "Operators", "Pragmatists", "Skeptics"],
    "Description": [
        "report having scaled AI use cases across multiple business units or functions",
        "report having implemented AI in at least one function with clear ROI",
        "report having started AI experiments or proofs of concept",
        "report exploring AI technologies but have not yet taken action"
    ],
    "Value": [45, 32, 28, 18]
})

plot_waffle_chart(
    data=data,
    width=1000,
    height=600,
    title='Generative AI adoption is accelerating, but scaling challenges remain.',
    subtitle='Enterprise AI readiness and integration, % of organizations surveyed',
)

Output:

8. Bubble Matrix Chart

Encode multi-dimensional categorical data using bubble sizes (for volume) and colors (for impact or scale), automatically laid out in a clean matrix.

import pandas as pd
from clean_charts import plot_bubble_matrix_chart

data = pd.DataFrame({
    "Industry": [
        "Financial Services",
        "Healthcare & Pharma",
        "Retail & Consumer Goods",
        "Manufacturing & Automotive",
        "Technology & Telecommunications",
        "Energy & Materials"
    ],
    "Marketing & Sales": [35, 22, 58, 18, 45, 12],
    "Product & Service Development": [42, 38, 25, 52, 75, 28],
    "IT & Cyber Operations": [65, 45, 38, 40, 82, 35],
    "Supply Chain & Logistics": [8, 15, 62, 70, 25, 55],
    "Human Resources": [25, 18, 22, 15, 30, 10],
    "Risk & Compliance": [72, 55, 12, 18, 28, 20]
})

title = "The state of AI adoption across industries"
subtitle = "Percentage of organizations reporting AI adoption in at least one function, by industry and business function, 2023"

plot_bubble_matrix_chart(
    data, 
    width=1000, 
    height=700, 
    title=title,
    subtitle=subtitle
)

Output:

9. Insight Card

Create a bold, solid-color card with large typographic text, optional subtext, and an optional image — ideal for callout quotes, key findings, or section dividers in dashboards.

from clean_charts import plot_insight_card

plot_insight_card(
    text="Building a new habit at work is straight forward in theory, but making it stick takes structure.",
    subtext="According to a new survey of 5,000 managers, structure is the #1 predictor of successfully adopting new team habits.",
    image_path="Images/right.png",
    aspect_ratio='1:1',
)

Output:

10. Data Table

Generate highly customizable, publication-quality data tables with automated text wrapping, row/column multi-indexes, configurable alignment, and dynamic conditional formatting (e.g. pills, heatmaps).

import pandas as pd
from clean_charts import plot_table

# 1. Dataset
df_tech = pd.DataFrame(
    [
        [45000, 3100.5, 0.082, 48500, 3450.0, 0.055],
        [12500, 850.2, 0.125, 14200, 1100.0, 0.152],
        
        [8500,  1250.0, -0.041, 8200, 1100.0, -0.051],
        [32000, 2400.0, 0.021, 33500, 2650.0, 0.028],
        [6500,  450.5, 0.054, 7100, 520.0, 0.061],
        
        [4200,  180.0, 0.185, 5100, 240.0, 0.215],
        [2800,  95.5, 0.245, 3600, 145.0, 0.285],
        [1500,  45.0, 0.081, 1650, 52.0, 0.095],
    ],
    index=pd.MultiIndex.from_tuples([
        ('Software Engineering', 'Backend Team'),
        ('Software Engineering', 'DevOps & Infra'),
        
        ('Hardware Engineering', 'Chip Design'),
        ('Hardware Engineering', 'Manufacturing'),
        ('Hardware Engineering', 'Supply Chain'),
        
        ('Sales & Marketing', 'Enterprise Sales'),
        ('Sales & Marketing', 'Digital Marketing'),
        ('Sales & Marketing', 'Public Relations'),
    ], names=['Department', 'Division']),
    columns=pd.MultiIndex.from_product([
        ['FY 2025 (Actuals)', 'FY 2026 (Projections)'],
        ['Headcount', 'Budget Allocation', 'YoY Growth']
    ], names=['Fiscal Year', 'Metrics'])
)

# 2. Table Configuration
col_format = [
    {"format": "{:,.0f}", "align": "right", "header_align": "right"},    # Headcount (No highlights)
    {"format": "${:.1f}M", "align": "right", "header_align": "right"},   # Budget
    {"format": "{:+.1%}", "align": "right", "header_align": "right"}     # YoY Growth
]

# 3. Generate the Plot
plot_table(
    data=df_tech,
    title="Global Tech Corp: Departmental Resource Allocation",
    subtitle="Headcount and budgetary shifts across software, hardware, and commercial departments.\nComparing FY 2025 actuals against FY 2026 projections.",
    columns=col_format * 2,  
    highlightRules=[
        # Heatmap for Budget Allocation (Cols 1 & 4)
        {"col": 1, "condition": "range", "min_color": "#ffc4b2", "max_color": "#b2ccb9"}, 
        {"col": 4, "condition": "range", "min_color": "#ffc4b2", "max_color": "#b2ccb9"},
        
        # Positive/Negative for YoY Growth (Cols 2 & 5)
        {"col": 2, "condition": "positive-negative"},
        {"col": 5, "condition": "positive-negative"}
    ],
    width=1100
)

Output:

11. Geofacet Map Chart

Visualize geographic data across the United States using a grid that roughly approximates the physical map. Supports three display modes: text (classic heatmap statebins), donut (progress arcs), and bar (horizontal progress bars).

import pandas as pd
import numpy as np
from clean_charts.plots import plot_geofacet

# 1. Generate data for US States
states = [
    'AL', 'AK', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DE', 'FL', 'GA', 
    'HI', 'ID', 'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'ME', 'MD', 
    'MA', 'MI', 'MN', 'MS', 'MO', 'MT', 'NE', 'NV', 'NH', 'NJ', 
    'NM', 'NY', 'NC', 'ND', 'OH', 'OK', 'OR', 'PA', 'RI', 'SC', 
    'SD', 'TN', 'TX', 'UT', 'VT', 'VA', 'WA', 'WV', 'WI', 'WY', 'DC'
]

df = pd.DataFrame({
    'state': states,
    'adoption_pct': np.random.uniform(10, 85, size=len(states))
})

# 2. Render the Geofacet
plot_geofacet(
    data=df,
    display_type="bar",
    max_value=100.0,
    title="Renewable Energy Adoption by State",
    subtitle="Tracking progress toward the 100% clean energy goal. (Bar style)",
    width=900
)

Output:

12. Dumbbell Chart

Visualize the difference between two values (e.g. start and end periods) across categories using an elegant range dot chart.

import pandas as pd
from clean_charts import plot_dumbbell_chart

df = pd.DataFrame({
    "Country": ["United States", "China", "Germany", "United Kingdom", "India"],
    "2000": [10.25, 1.21, 1.94, 1.66, 0.47],
    "2020": [20.94, 14.72, 3.85, 2.76, 2.66],
})

plot_dumbbell_chart(
    data=df,
    title="Great expectations",
    subtitle="Top 5 countries by GDP, in trillions of USD"
)

Output:

13. Dashboard (Multi-Chart Layout)

Combine any mix of chart types into a single, cohesive dashboard image using plot_dashboard. Each sub-chart is rendered independently and composited onto a unified mosaic — no manual subplot wrangling needed.

import pandas as pd
from clean_charts import (
    plot_time_series,
    plot_barh_chart,
    plot_donut_chart,
    plot_stacked_bar_chart,
    plot_dashboard,
)

# Prepare individual datasets
df_ts = pd.DataFrame({
    'Dates':   pd.date_range("2026-01-01", periods=12, freq="MS"),
    'Apples':  [500, 596, 590, 523, 582, 515, 501, 551, 494, 467, 548, 490],
    'Bananas': [350, 339, 349, 382, 328, 359, 403, 390, 459, 390, 373, 437],
})

df_bar = pd.DataFrame({
    'Category': ['Apples', 'Bananas', 'Cherries', 'Dates', 'Elderberries'],
    'Sales':    [400, 350, 300, 450, 120],
})

df_donut = pd.DataFrame({
    'Category': ['Apples', 'Bananas', 'Cherries', 'Dates'],
    'Sales':    [400, 350, 300, 450],
})

df_stacked = pd.DataFrame({
    'Year':     ['2023', '2024', '2025', '2026'],
    'Apples':   [360, 380, 510, 415],
    'Bananas':  [405, 410, 180, 450],
    'Cherries': [140, 150, 830, 590],
})

# Build the dashboard
plot_dashboard(
    charts=[
        (plot_time_series,       {"data": df_ts,      "title": "Monthly Trend"}),
        (plot_barh_chart,        {"data": df_bar,     "title": "Top Items"}),
        (plot_donut_chart,       {"data": df_donut,   "title": "Market Share"}),
        (plot_stacked_bar_chart, {"data": df_stacked, "title": "Yearly Breakdown"}),
    ],
    layout="AB\nCD",           # 2×2 grid
    title="Fruit Sales Overview — Q1 2026",
    subtitle="A consolidated view of inventory, sales trends, and category distribution",
    width=1400,
)

How it works

1. charts — A list of (plot_function, kwargs_dict) tuples. You can use any Clean Charts plot function (plot_time_series, plot_barh_chart, plot_barv_chart, plot_grouped_barh_chart, plot_donut_chart, plot_stacked_bar_chart, plot_waffle_chart, plot_bubble_matrix_chart, plot_insight_card, plot_geofacet). Do not include output_path in the kwargs — it is managed automatically.

2. layout — An ASCII mosaic string where each unique letter maps to one chart in order. Use repeated letters to span cells across rows or columns:

   "AB\nCD"    →  2×2 grid (default for 4 charts)
   "AA\nBC"    →  chart A spans the entire top row (2 columns)
   "AB\nAC"    →  chart A spans the entire left column (2 rows)
   "AB\nCC"    →  chart C spans the entire bottom row
   "AAB\nCDD"  →  3-column layout with mixed spans
   "ABC"       →  single row, three equal columns
   "AA\nAA"    →  one chart fills the entire canvas
   

   If omitted, charts are auto-arranged in a roughly square grid.

3. Consistent styling — All sub-charts share a unified scale factor and pixel margins, so titles, subtitles, labels, and margins align perfectly across all charts — even when charts span multiple columns or rows.

Multi-span layout example

Charts spanning 2+ columns or rows have the same title size and positioning as 1×1 charts:

# Wide chart on top, two standard charts below
plot_dashboard(
    charts=[
        (plot_time_series, {"data": df_ts, "title": "Revenue Trend", "subtitle": "24-month overview"}),
        (plot_barh_chart,  {"data": df_bar, "title": "Top Items", "subtitle": "By sales volume"}),
        (plot_donut_chart, {"data": df_donut, "title": "Market Share", "subtitle": "By category"}),
    ],
    layout="AA\nBC",
    title="Executive Summary",
    width=1400,
)

Output:

🎨 Customizing Data & Advanced Usage

import pandas as pd
from clean_charts import plot_time_series

data = pd.DataFrame({
    "Day": pd.date_range("2026-05-01", periods=10, freq="D"),
    "Active Users": [120, 150, 190, 240, 220, 250, 270, 310, 340, 320],
    "Signups":      [15,  22,  35,  40,  28,  30,  32,  45,  52,  48],
})

plot_time_series(
    data=data,
    output_path="daily_stats.png",
    title="Daily Server Growth",
    subtitle="Active users and registrations in May 2026",
    label_frequency="day",   # "year" | "quarter" | "month" | "week" | "day" | "hour" | "minute" | "second"
    start_color="#006400",   # Dark green gradient start
    end_color="#ffd700",     # Gold gradient end
    smooth=True,             # Smooth PCHIP spline curves (default True)
    markers=True,            # Show circle markers on data points
    line_labels="both",      # Show "Series: value" inline labels
    value_suffix="%",        # Append "%" to Y-axis ticks and inline labels
)

import pandas as pd
from clean_charts import plot_barh_chart

df = pd.DataFrame({
    "Category":    ["Apples", "Bananas", "Cherries", "Dates", "Elderberries", "Figs", "Grapes", "Honeydew"],
    "Sales (tons)":[400,      350,       300,        450,     120,            210,    520,      180],
})

plot_barh_chart(
    data=df,
    output_path="fruit_sales.png",
    title="Fruit Performance Analysis",
    subtitle="Total sales volume by item",
    value_suffix=" t",
    color="#1f77b4",
)

import pandas as pd
from clean_charts import plot_grouped_barh_chart

df = pd.DataFrame({
    "Country": ["Germany", "France", "Italy", "Spain", "Poland"],
    "BEV":     [18, 14, 8, 5, 3],
    "PHEV":    [9,  7,  5, 4, 2],
    "Hybrid":  [22, 19, 12, 9, 6],
})

plot_grouped_barh_chart(
    data=df,
    output_path="ev_by_country.png",
    title="EV Adoption by Country",
    subtitle="Share of new car sales by powertrain, %",
    value_suffix="%",
    bar_labels="value",       # "none" | "value" | "name" | "both"
    start_color="#005f73",
    end_color="#94d2bd",
)

📖 API Reference

"AB\nCD"   →  2×2 grid (default for 4 charts)
"AA\nBC"   →  chart A spans full top row (2 columns)
"AB\nAC"   →  chart A spans full left column (2 rows)
"AB\nCC"   →  chart C spans full bottom row
"AAB\nCDD" →  3-column layout with mixed spans
"ABC"      →  single row, three equal columns
"AA\nAA"   →  one chart fills the entire canvas

from clean_charts import get_default_data

df = get_default_data()
print(df.head())

🎛️ Global Customization

import clean_charts.config as config
from clean_charts import plot_time_series

# Override styling tokens before plotting
config.BACKGROUND_COLOR = "#ffffff"  # Pure white background
config.GRID_COLOR        = "#eaeaea"  # Light gridlines
config.AXIS_COLOR        = "#333333"  # Dark charcoal axes

plot_time_series(
    title="Custom White Theme",
    output_path="white_theme_chart.png"
)

🧪 Examples & Development

Generate Sample Charts

python generate_sample.py

This produces a set of sample images showcasing different aspect ratios, gradient themes, label frequencies, and title-wrapping behavior.

Running Tests

python -m unittest tests/test_plot.py

📄 License

MIT © Raghuram Sirigiri