# `clean_charts` Package Documentation for LLMs

## Overview
`clean_charts` (imported as `cc`) is a Python library for rendering publication-quality, Economist-style charts. All chart functions accept a pandas DataFrame and return styled visualizations.

## Global Parameters
Almost all chart functions share these common parameters:
- `data` (pd.DataFrame): Input tabular data.
- `output_path` (str | None): File path to save the chart (.png, .jpg, .pdf, .svg). If None, displays inline.
- `width`, `height` (int | None): Explicit image dimensions in pixels.
- `aspect_ratio` (str | None): Semantic sizing ("square", "landscape", "vertical", "1:1", "2:1", "1:2"). Overrides width/height.
- `title`, `subtitle` (str | None): Header text.
- `bg_color` (str | None): Background hex color. Defaults to Economist cream (#f4f3f0).
- `scale_text` (bool): Scale fonts proportionally with image size.
- `value_suffix` (str): String appended to labels/ticks (e.g., "%", "M").
- `show_percentages` (bool): Format numeric values as percentages.

Color conventions:
- `color`: single hex color for all elements.
- `start_color` / `end_color`: gradient boundary colors.
- `colors`: explicit list of hex colors.

---
## Chart Selection Guide
- **Rankings/Categorical Comparisons**: `plot_barh_chart`, `plot_barv_chart`
- **Multi-series Comparisons**: `plot_grouped_barh_chart`, `plot_grouped_scatter_chart`
- **Part-to-whole / Proportions**: `plot_stacked_bar_chart`, `plot_donut_chart`, `plot_waffle_chart`
- **Relationships / Scatter**: `plot_scatter_chart`, `plot_bubble_scatter_chart`
- **Time Trends / Shifts**: `plot_time_series`, `plot_dumbbell_chart`
- **Grids / Matrices**: `plot_bubble_matrix_chart`, `plot_table`, `plot_geofacet`
- **Highlights**: `plot_insight_card`, `plot_dashboard` (composites)

---
## Chart References

### 1. Horizontal Bar Chart (`plot_barh_chart`)
**Use Case**: Comparing 2-10 categories with long text labels. Ranks items.
**Data Requirements**: 2 columns [Category labels (str), Values (numeric)]. Sort DataFrame for ranking.
**Unique Parameters**:
- `color` (str): Hex color for bars.
- `bar_padding` (float): Gap between bars (0-1). Higher = thinner bars.
**Example**:
```python
cc.plot_barh_chart(
    data=df, title="Top Countries", subtitle="2024",
    bar_padding=0.6, color="#000000", value_suffix=" pts"
)
```

### 2. Vertical Bar Chart (`plot_barv_chart`)
**Use Case**: Ordinal data or short labels (e.g., quarters, months). Timeline histogram.
**Data Requirements**: 2 columns [Category labels, Values].
**Unique Parameters**:
- `color` (str): Hex color for bars.
- `bar_padding` (float): Gap between bars (0-1).
**Example**:
```python
cc.plot_barv_chart(
    data=df, title="Quarterly Revenue", aspect_ratio="square", bar_padding=0.4
)
```

### 3. Bubble Matrix Chart (`plot_bubble_matrix_chart`)
**Use Case**: 3D data in a grid (Row, Col, Size). Skill matrices, risk heatmaps.
**Data Requirements**: Col 0: Row labels. Cols 1..N: Numeric values (column headers become col labels).
**Unique Parameters**:
- `start_color`, `end_color` (str): Gradient colors based on value.
- `show_values` (bool): Print values inside bubbles.
**Example**:
```python
cc.plot_bubble_matrix_chart(
    data=df, title="Risk Assessment", show_values=True, end_color="#FFA896", start_color="#9B1313"
)
```

### 4. Bubble Scatter Chart (`plot_bubble_scatter_chart`)
**Use Case**: 3-variable scatter plot (X, Y, Bubble Size). Portfolio analysis.
**Data Requirements**: 3 cols [X, Y, Size] or 4 cols [Label, X, Y, Size].
**Unique Parameters**:
- `min_bubble_size`, `max_bubble_size` (float): Bubble area points.
- `start_color`, `end_color`, `color` (str): Colors.
- `alpha` (float): Transparency (0-1).
- `show_values`, `show_labels` (bool): Annotate bubbles.
- `x_label`, `y_label` (str): Axis labels.
**Example**:
```python
cc.plot_bubble_scatter_chart(
    data=df, title="Market Sizing", x_label="Cost", y_label="Income", alpha=0.6
)
```

### 5. Dashboard (`plot_dashboard`)
**Use Case**: Combine multiple charts into a single mosaic image.
**Data Requirements**: None for the dashboard itself (uses other charts).
**Unique Parameters**:
- `charts` (list[tuple]): List of `(plot_function, kwargs_dict)` tuples.
- `layout` (str | None): ASCII layout string (e.g., "AB\nCD").
- `padding` (float): Space between sub-charts.
**Example**:
```python
cc.plot_dashboard(
    charts=[
        (cc.plot_time_series, {"data": df_ts, "title": "Trends"}),
        (cc.plot_donut_chart, {"data": df_donut, "title": "Sources"})
    ],
    layout="AB", title="Exec Summary"
)
```

### 6. Donut Chart (`plot_donut_chart`)
**Use Case**: Part-to-whole compositions with center label (up to 8 segments).
**Data Requirements**: 2 cols [Labels, Values].
**Unique Parameters**:
- `start_color`, `end_color` (str): Gradient for segments.
- `center_label` (str): Bold text inside ring. Use `\n` for multiline.
- `hole_radius`, `donut_radius` (float): Size controls.
**Example**:
```python
cc.plot_donut_chart(
    data=df, title="Revenue Mix", center_label="$42M\nTotal", show_percentages=True
)
```

### 7. Dumbbell Chart (`plot_dumbbell_chart`)
**Use Case**: Connected dot chart. Before vs after deltas.
**Data Requirements**: 3 cols [Category, Start values, End values].
**Unique Parameters**:
- `start_color`, `end_color`, `connector_color` (str): Colors.
- `dot_size` (float): Marker size.
- `show_values` (bool): Show numeric values next to dots.
**Example**:
```python
cc.plot_dumbbell_chart(
    data=df, title="Target vs Actual", show_values=True, end_color="#FD8302", start_color="#0241FD"
)
```

### 8. Geofacet Map (`plot_geofacet`)
**Use Case**: Geographic small-multiples grid approximating physical map.
**Data Requirements**: Col with state/region abbreviations, col with values.
**Unique Parameters**:
- `state_col`, `value_col` (str): Column names.
- `layout` (str): Grid layout (e.g., "us", "uk").
- `display_type` (str): "text", "donut", "bar".
- `max_value` (float): Scale reference.
- `start_color`, `end_color`, `missing_color` (str): Colors.
**Example**:
```python
cc.plot_geofacet(
    data=df, layout="us", display_type="donut", max_value=100.0, title="EV Adoption"
)
```

### 9. Grouped Horizontal Bar (`plot_grouped_barh_chart`)
**Use Case**: Multi-series categorical comparisons (subgroups across categories).
**Data Requirements**: Col 0: Labels. Cols 1..N: Numeric series.
**Unique Parameters**:
- `start_color`, `end_color` (str): Gradient across series.
- `bar_padding`, `group_padding` (float): Spacing.
- `bar_labels` (str): "none", "value", "name", "both".
- `group_comments` (list[dict]): Per-group annotations (`heading`, `subtitle`, `big_number`).
- `group_separators` (bool): Draw lines between groups.
**Example**:
```python
cc.plot_grouped_barh_chart(
    data=df, title="Tech Revenue", bar_labels="value", group_separators=True
)
```

### 10. Grouped Scatter Chart (`plot_grouped_scatter_chart`)
**Use Case**: Quadrant matrix or categorically grouped scatter plot.
**Data Requirements**: Categorical: [Label, X, Y, Category]. Quadrant: [Label, X, Y].
**Unique Parameters**:
- `group_by` (str): "category" or "quadrant".
- `x_threshold`, `y_threshold` (float): Threshold lines.
- `quadrant_labels` (list[str]): Top-right, top-left, bottom-left, bottom-right.
- `show_threshold_lines`, `show_labels` (bool).
- `colors`, `start_color`, `end_color` (list/str): Colors.
**Example**:
```python
cc.plot_grouped_scatter_chart(
    data=df, group_by="quadrant", x_threshold=50, y_threshold=50
)
```

### 11. Insight Card (`plot_insight_card`)
**Use Case**: Hero stats, big callouts.
**Data Requirements**: None. Uses text parameters.
**Unique Parameters**:
- `text`, `subtext` (str): Main text and secondary text.
- `image_path` (str): Image at bottom.
- `text_color` (str): Text hex color.
**Example**:
```python
cc.plot_insight_card(
    text="Record $4.2B", bg_color="#000", text_color="#fff"
)
```

### 12. Basic Scatter Chart (`plot_scatter_chart`)
**Use Case**: 2D scatter for relationships between two continuous variables.
**Data Requirements**: 2 cols [X, Y] or 3 cols [Labels, X, Y].
**Unique Parameters**:
- `color` (str): Hex color.
- `dot_size`, `alpha` (float): Size and transparency.
- `x_label`, `y_label`, `x_suffix`, `y_suffix` (str): Axis config.
- `show_labels`, `show_trendline` (bool).
- `trendline_color` (str).
**Example**:
```python
cc.plot_scatter_chart(
    data=df, show_labels=True, show_trendline=True, trendline_color="#635bff"
)
```

### 13. Stacked Bar Chart (`plot_stacked_bar_chart`)
**Use Case**: Part-to-whole distribution across categories.
**Data Requirements**: Col 0: Labels. Cols 1..N: Stacked series.
**Unique Parameters**:
- `colors` (list[str]): Explicit colors for stack.
- `start_color`, `end_color` (str): Gradient colors.
- `bar_padding` (float): Spacing.
- `bar_labels` (str): "none", "value", "name", "both".
**Example**:
```python
cc.plot_stacked_bar_chart(
    data=df, title="Energy Mix", show_percentages=True, bar_labels="value"
)
```

### 14. Data Table (`plot_table`)
**Use Case**: Economist-style table with conditional formatting.
**Data Requirements**: DataFrame (MultiIndex supported).
**Unique Parameters**:
- `columns` (list[dict]): Column configs (width_pct, align).
- `cellStyles` (dict): `(row, col)` styles.
- `highlightRules` (list[dict]): e.g., positive-negative or range shading.
**Example**:
```python
cc.plot_table(
    data=df, highlightRules=[{"col": 1, "condition": "positive-negative"}]
)
```

### 15. Time Series (`plot_time_series`)
**Use Case**: Multi-series line charts with annotations.
**Data Requirements**: Date/Time column + numeric columns.
**Unique Parameters**:
- `start_color`, `end_color` (str): Colors.
- `label_frequency` (str): "year", "quarter", "month", etc.
- `smooth` (bool): Spline curves (default True).
- `vlines`, `highlight_ranges`, `callouts` (list[dict]): Annotations.
**Example**:
```python
cc.plot_time_series(
    data=df, label_frequency="quarter",
    vlines=[{"date": "2024-07-01", "label": "Launch"}]
)
```

### 16. Waffle Chart (`plot_waffle_chart`)
**Use Case**: 10x10 dot grid for precise "X out of 100".
**Data Requirements**: 2 cols [Category, Percentage] or 3 cols [Label, Category, Percentage].
**Unique Parameters**:
- `color`, `inactive_color` (str): Filled and unfilled dot colors.
**Example**:
```python
cc.plot_waffle_chart(data=df, title="Priorities", color="#0066cc")
```
