Metadata-Version: 2.4
Name: clean-charts
Version: 0.2.3
Summary: A Python library to generate beautiful, clean charts in premium visual styles
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: pillow>=8.0.0
Dynamic: license-file

# 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:

```bash
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.

```python
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:
![Line Chart](https://raw.githubusercontent.com/raghuramsirigiri/Viz_images/main/time_series.png)

### 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.

```python
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:
![Barh Chart](https://raw.githubusercontent.com/raghuramsirigiri/Viz_images/main/barh.png)

---

## 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.

```python
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.

```python
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:

```python
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:

```bash
python generate_sample.py
```

### Running Tests
To run the unit tests suite:

```bash
python -m unittest tests/test_plot.py
```
