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.

✨ 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,
    title="Regional Supermarket Inventory and Fruit Category Performance Analysis",
    subtitle="Comparative overview of total stock volume across key produce items",
    value_suffix=' Kg',
)

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

df = pd.DataFrame({
    "Label": ["Visionaries", "Operators", "Pragmatists", "Skeptics", "Laggards"],
    "Description": [
        "report they focus 30% or more of their time on long-term growth initiatives",
        "increase resourcing for growth initiatives in core, adjacent, or new businesses during periods of volatility",
        "consistently incorporate customer input into business decisions",
        "express high confidence in their organizations' talent planning",
        "feel strongly they have sufficient data and insights to support their growth decisions"
    ],
    "Value": [29, 30, 15, 8, 10]
})

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

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

# Volume mapping
data = pd.DataFrame({
    "User Segment": ["New Users", "Returning", "Power Users", "Lapsed"],
    "Variant A": [1500, 2200, 800, 500],
    "Variant B": [1450, 2150, 850, 480],
    "Variant C": [1520, 2300, 820, 510],
})

# Uplift mapping
uplift_data = pd.DataFrame({
    "User Segment": ["New Users", "Returning", "Power Users", "Lapsed"],
    "Variant A": [1.2, 0.5, 3.4, -0.5],
    "Variant B": [4.5, 2.1, -1.2, 1.1],
    "Variant C": [0.8, 5.5, 4.2, 0.2],
})

plot_bubble_matrix_chart(
    data=data,
    color_data=uplift_data,
    title="Sales Funnel Optimization: Q3 A/B Test Results",
    subtitle="Bubble size indicates sample volume. Color and values indicate % uplift.",
    start_color="#E74C3C",
    end_color="#2ECC71",
    value_suffix="%"
)

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="Supply chain optimizations have increased total stock efficiency by 15% year-over-year.",
    subtext="According to the Q3 logistics report, regional hubs are processing inbound shipments faster than ever.",
    image_path="path/to/graphic.png",  # Optional
    aspect_ratio='1:1',
)

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

Custom Time-Series Data

Supply your own pandas.DataFrame containing a date/time column and one or more value columns. The library automatically parses the datetime column and maps all other numeric columns as lines.

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
)

Custom Horizontal Bar Chart Data

Pass a pandas.DataFrame where the first column contains string labels and the second column contains numeric values.

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",
)

Custom Grouped Bar Chart Data

Pass a DataFrame whose first column contains category labels and each subsequent column represents one series.

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

plot_time_series

plot_barh_chart

plot_grouped_barh_chart

plot_donut_chart

plot_stacked_bar_chart

plot_barv_chart

plot_waffle_chart

plot_bubble_matrix_chart

plot_insight_card

plot_dashboard

Combine multiple charts into a single composite image using a mosaic layout. Charts that span multiple columns or rows are rendered with the same title size and margin alignment as single-cell charts.

Layout examples:

"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

Alignment note: All sub-charts automatically share a unified scale factor and pixel margins, ensuring titles, subtitles, labels, and axes are perfectly aligned across charts — even when they span different numbers of grid cells.

🎛️ Global Customization

Import and modify global configuration variables to apply a consistent theme across all charts:

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"
)

Available Config Variables (clean_charts.config)

🧪 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