clean-charts 0.2.2

A Python library to generate beautiful, clean charts in premium visual styles

Clean Charts Library

A Python library to generate line charts in clean, premium visual styles, including right-aligned axes, custom year boundaries, distinct line colors, and dynamic scaling for mini canvas resolutions.

The library automatically identifies date/time columns and any number of value series to plot them dynamically, with overlap-avoiding label placement, and allows custom color interpolation, date label frequencies, titles, and subtitles.

Installation

pip install .

Quick Start

You can run the script without any parameters to recreate the chart from the reference image:

from clean_charts import plot_time_series

# Generates the default landscape image (1000x500)
plot_time_series(
    output_path="chart_landscape.png", 
    aspect_ratio="landscape",
    title="Europe",
    subtitle="Sales of Chinese-made cars, % of total"
)

# Generates a 500x500 square visualization
plot_time_series(
    output_path="chart_500.png", 
    width=500, 
    height=500,
    title="Europe",
    subtitle="Sales of Chinese-made cars, % of total"
)

# Generates a chart with a custom color gradient (from Indigo to Coral)
plot_time_series(
    output_path="chart_gradient.png",
    start_color="#4b0082",
    end_color="#ff7f50",
    title="EV Market Split",
    subtitle="Gradient Theme Demonstration"
)

Custom Data Input and X-Axis Frequencies

You can supply your own pandas DataFrame with any date/time column and value columns. The library dynamically identifies them and configures the X-axis label frequency:

import pandas as pd
from clean_charts import plot_time_series

# Day-frequency dataset example
daily_data = pd.DataFrame({
    "Day": pd.date_range("2026-05-01", periods=10, freq="D"),
    "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=daily_data,
    output_path="daily_chart.png",
    title="Server Statistics",
    subtitle="10-Day Signups growth",
    label_frequency="day", # Supported: "year", "quarter", "month", "week", "day", "hour", "minute", "second"
    start_color="#006400",
    end_color="#ffd700"
)

Example of Line Chart:

Horizontal Bar Chart

You can supply your own pandas DataFrame with category and value columns.

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,
    output_path="chart.png",
    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',
    color = '#000000'
)

Example of Barh Chart: