clean-charts 0.2.3

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

Clean Charts

clean-charts is a lightweight, premium Python library designed to generate beautiful, publication-quality data visualizations (inspired by modern publication designs like The Economist).

Featuring right-aligned axes, custom date boundaries, distinct line colors, automatic overlap-avoiding label placement, and dynamic scaling for varying canvas resolutions, clean-charts makes it effortless to create presentation-ready visualizations.

---

Key Features

• Premium Aesthetics: Light cream-gray backgrounds, minimal gridlines, elegant typography, and consistent padding.
• Time-Series Line Charts (plot_time_series):
  • Right-aligned Y-axes.
  • Automatically identifies date/time columns and handles multiple value series.
  • Generates custom color gradients or uses a refined default palette.
  • Intelligently spaces dates and years on the X-axis to prevent label overlap.
  • Smart label placement that directly labels lines at their endpoints (avoiding messy legends).
• Horizontal Bar Charts (plot_barh_chart):
  • Left-aligned categories and titles.
  • Top-aligned numeric ticks with custom suffixes (e.g., %, x, kg).
  • Values labeled inside/outside the end of each bar.
• Responsive Scaling: All text, line-weights, and paddings scale proportionally based on target width and height.

---

Installation

Install the package directly from the local directory:

pip install clean-charts

---

Quick Start

1. Line Chart (Time Series)

By default, calling plot_time_series without any arguments uses a built-in sample dataset mapping automobile sales types from 2020 to 2025.

from clean_charts import plot_time_series

# Recreate a standard landscape chart (1000x562)
plot_time_series(
    output_path="chart_landscape.png",
    aspect_ratio="landscape",
    title="Europe",
    subtitle="Sales of Chinese-made cars, % of total"
)

Output Example:

2. Horizontal Bar Chart

Draw a horizontal bar chart with categories and value labels. If no data is provided, it uses a default survey dataset.

from clean_charts import plot_barh_chart

# Create a clean horizontal bar chart with custom title and suffix
plot_barh_chart(
    output_path="chart_barh.png",
    title="Super Bowl Viewer Interest",
    subtitle="Are you planning to watch the game this Sunday?",
    value_suffix="%"
)

Output Example:

---

Customizing Data & Advanced Usage

Custom Time-Series Data

You can 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

# 1. Prepare your dataset
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]
})

# 2. Plot with custom color gradient and day-level label frequency
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",  # Supported: "year", "quarter", "month", "week", "day", "hour", "minute", "second"
    start_color="#006400",  # Dark Green gradient start
    end_color="#ffd700",    # Gold gradient end
)

Custom Horizontal Bar Chart Data

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

import pandas as pd
from clean_charts import plot_barh_chart

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

# 2. Render horizontal bar chart
plot_barh_chart(
    data=df,
    output_path="fruit_sales.png",
    title="Fruit Performance Analysis",
    subtitle="Total sales volume by item to optimize supply chain distribution",
    value_suffix=" t",
    color="#1f77b4"  # Hex color code for the bars
)

---

API Reference

plot_time_series

Parameter	Type	Default	Description
data	pd.DataFrame	None	DataFrame containing datetime column and value series columns. If None, uses built-in default data.
output_path	str	"chart.png"	File path to save the generated image.
width	int	1000	Target width of the image in pixels.
height	int	562	Target height of the image in pixels.
aspect_ratio	str	None	Predefined aspect ratio: "square" (or "1:1"), "landscape" (or "2:1"), "vertical" (or "1:2"). Overrides width/height if set.
title	str	None	Main title text displayed in bold at the top left.
subtitle	str	None	Subtitle text displayed below the title.
start_color	str	None	Hex color code for the first line series gradient boundary.
end_color	str	None	Hex color code for the last line series gradient boundary.
label_frequency	str	"year"	X-axis label frequency: "year", "quarter", "month", "week", "day", "hour", "minute", "second".
scale_text	bool	True	Automatically scale text fonts, line widths, and pad widths proportionally.

plot_barh_chart

Parameter	Type	Default	Description
data	pd.DataFrame	None	DataFrame with column 0 as category strings and column 1 as numeric values. If None, uses built-in survey data.
output_path	str	"bar_chart.png"	File path to save the generated image.
width	int	600	Target image width in pixels.
height	int	None	Target image height in pixels. Auto-sized dynamically based on the number of categories if None.
aspect_ratio	str	None	Predefined aspect ratio: "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
title	str	None	Main title text displayed in bold.
subtitle	str	None	Subtitle text displayed below the title.
color	str	None	Hex color for the bars. If None, defaults to the config's line color.
bar_padding	float	0.35	Fraction of bar slot left as gap between bars (0.0 to 1.0).
value_suffix	str	""	String appended to value labels and axis ticks (e.g. "%").
scale_text	bool	True	Automatically scale text fonts and margins proportionally.

---

Global Customization

You can import and change the global configuration styling variables dynamically:

import clean_charts.config as config
from clean_charts import plot_time_series

# Modify styling tokens globally
config.BACKGROUND_COLOR = "#ffffff"  # Set background to pure white
config.GRID_COLOR = "#eaeaea"        # Lighten gridlines
config.AXIS_COLOR = "#333333"        # Dark charcoal axis

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

Available config variables (in clean_charts.config):

• BACKGROUND_COLOR (default: "#f4f3f0")
• GRID_COLOR (default: "#dcdbd7")
• AXIS_COLOR (default: "#000000")
• TITLE_COLOR (default: "#111111")
• SUBTITLE_COLOR (default: "#444444")
• LINE_COLOR (default: "#000000")

---

Examples & Development

Run Samples

To generate all sample charts showing various aspect ratios, gradients, and custom frequencies, run the provided sample script:

python generate_sample.py

Running Tests

To run the unit tests suite:

python -m unittest tests/test_plot.py