# clean-charts LLM API Reference & Usage Guide

This file serves as the definitive guide for Large Language Models (LLMs) interacting with the `clean-charts` Python package. It contains explicit instructions, type constraints, and contextual examples to ensure hallucination-free code generation.

---

## 🧠 1. Core Concepts & Package Philosophy

`clean-charts` is designed to produce Economist-style, publication-ready charts. 
- **Style:** Minimalist, cream-gray background (`#E5E1D8`), bold titles, flush-left alignment, and a signature red accent line above the title.
- **Data Requirement:** The library heavily relies on `pandas.DataFrame`. Always ensure data is properly formatted before passing it to any plotting function.
- **Output:** The functions do not return matplotlib `Figure` objects; they handle the drawing and saving directly to `output_path`.

---

## 🛠️ 2. Comprehensive Parameter Guide & Examples

Almost all functions share a common set of parameters. Here is the highly detailed breakdown of what they are, what options are valid, and when to use them:

### `data` (pandas.DataFrame)
- **What it is:** The tabular data to be plotted.
- **Format:** Usually requires a very specific 2-column format (e.g., Column 1: Categories (str), Column 2: Values (numeric)).
- **Example:**
  ```python
  import pandas as pd
  df = pd.DataFrame({"Response": ["Yes", "No"], "Percentage": [65, 35]})
  ```
- **When to use:** ALWAYS required unless you are testing, in which case leaving it as `None` uses built-in sample data.

### `output_path` (str)
- **What it is:** The absolute or relative file path to save the generated chart.
- **Options:** `.png`, `.jpg`, `.jpeg`, `.pdf`, `.svg`.
- **Example:** `"charts/q3_earnings_barh.png"`
- **When to use:** ALWAYS. Clean-charts typically saves directly to disk.

### `aspect_ratio` (str)
- **What it is:** A semantic way to define the chart's dimensions instead of explicitly passing width/height.
- **Valid Options:**
  - `"square"` or `"1:1"`: Best for Social Media (Instagram), Donut Charts, and Insight Cards.
  - `"landscape"` or `"2:1"`: Best for Presentations (PowerPoint), Time Series, and Bar Charts.
  - `"vertical"` or `"1:2"`: Best for long tables or very long horizontal bar charts.
- **When to use:** Use this **IN PLACE OF** `width` and `height`. It ensures the layout scales correctly according to the Economist style.

### `width` & `height` (int)
- **What it is:** Explicit dimensions in pixels.
- **Example:** `width=800, height=600`
- **When to use:** ONLY use when `aspect_ratio` does not fit the target medium and specific pixel dimensions are strictly required.

### `title` & `subtitle` (str)
- **What it is:** The text headers for the chart. The title is bold and larger; the subtitle is lighter and smaller. Both are flush-left aligned.
- **Example:**
  - `title="Global inflation is easing"`
  - `subtitle="Consumer price index, % change on a year earlier"`
- **When to use:** Always include a descriptive title and subtitle. It is a core tenet of data journalism.

### `color` & `bg_color` (str)
- **What it is:** Hex codes for the accent elements (bars, lines) and the background.
- **Options:** Any valid hex code (e.g., `"#E3120B"` for Economist Red, `"#E5E1D8"` for Economist Background).
- **When to use:** By default, do not pass these as they default to the package's signature style. Only override if the user requests a custom color palette.

### `value_suffix` (str)
- **What it is:** A string appended to data labels and axis ticks.
- **Options:** `"%"` (percentages), `"x"` (multipliers), `"M"` (millions).
- **Example:** `value_suffix="k"` (turns 15 into 15k).
- **When to use:** Use when the numbers represent a specific unit that isn't clear from the subtitle.

### `show_percentages` (bool)
- **What it is:** Formats the numeric values as percentages (e.g., turns `0.25` into `25.0%`).
- **Options:** `True` or `False`.
- **When to use:** When the raw data is a decimal representation of a fraction.

---

## 📊 3. Chart Selection Decision Tree

If the user asks for a visualization, use this logic to pick the correct function:

1. **Are you comparing 2-10 categories with long text labels?** 
   👉 Use `plot_barh_chart` (Horizontal Bar)
2. **Are you comparing ordinal data or short-label categories (e.g., years, quarters)?** 
   👉 Use `plot_barv_chart` (Vertical Bar)
3. **Are you comparing trends over continuous time?** 
   👉 Use `plot_time_series`
4. **Are you comparing part-to-whole relationships?** 
   👉 2-5 items: `plot_donut_chart`
   👉 Multiple items across categories: `plot_stacked_bar_chart`
   👉 Showing precise grid proportions: `plot_waffle_chart`
5. **Are you comparing the SAME metric across TWO distinct time periods or groups?** 
   👉 Use `plot_dumbbell_chart`
6. **Are you comparing multiple subgroups across several primary categories?** 
   👉 Use `plot_grouped_barh_chart`
7. **Do you have 3 dimensions of data (Row, Column, Size)?** 
   👉 Use `plot_bubble_matrix_chart`
8. **Do you need to map data across regions/states?** 
   👉 Use `plot_geofacet`
9. **Do you just need to show a single massive KPI number?** 
   👉 Use `plot_insight_card`
10. **Do you need to show raw values with conditional formatting?** 
    👉 Use `plot_table`
11. **Do you need to put multiple of these charts together into one image?** 
    👉 Use `plot_dashboard`
12. **Are you comparing the relationship between two continuous variables (X vs Y)?** 
    👉 Use `plot_scatter_chart`
13. **Are you comparing the relationship between X and Y across different categories or quadrants?** 
    👉 Use `plot_grouped_scatter_chart`
14. **Are you comparing 3 continuous variables (X vs Y with Size)?** 
    👉 Use `plot_bubble_scatter_chart`

---

## 📚 4. Detailed API Reference

### `plot_barh_chart`

**Description:**
Plots a horizontal bar chart in the Economist style (as shown in the reference image).

The chart features:
  - Cream-gray background matching the Economist palette.
  - Horizontal bars in a single accent color (default Economist red).
  - Category labels left-aligned above each bar, flush with the axis left edge.
  - Title and subtitle also left-aligned to the same axis left edge.
  - Numeric value labels printed just inside the right end of each bar.
  - Numeric axis ticks along the top x-axis.
  - Equal padding on all four sides of the figure.
  - A short red rule rendered above the title (Economist signature detail).

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame with exactly two columns:
      - Column 0 (str): Category labels (e.g. "Don't care", "Yes", …).
      - Column 1 (numeric): Values to plot.
    Rows are displayed top-to-bottom in the order they appear in the DataFrame.
    If None, a built-in Super Bowl survey example is used.
output_path : str
    File path for the saved image (PNG/JPEG).
width : int
    Target image width in pixels. Defaults to 600.
height : int
    Target image height in pixels. Auto-sized when None.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
    Overrides explicit width/height when supplied.
title : str
    Bold title text (supports wrapping over 2 lines).
subtitle : str
    Lighter subtitle rendered below the title.
color : str
    Hex color for the bars.
bar_padding : float
    Fraction of bar slot left as gap between bars (0–1). Default 0.35.
value_suffix : str
    String appended to value labels and axis ticks (e.g. "%" or "x").
scale_text : bool
    Whether to scale fonts proportionally with image size.
show_percentages : bool
    If True, value labels show percentages (e.g., '25.0%') instead of raw values.
```

---

### `plot_barv_chart`

**Description:**
Plots a vertical bar chart in the Economist style.

The chart features:
  - Cream-gray background matching the Economist palette.
  - Vertical bars in a single accent color.
  - Category labels wrapped below each bar.
  - Numeric value labels printed just above the top of each bar.
  - Numeric axis ticks along the left y-axis with horizontal gridlines.
  - Equal padding on all four sides of the figure.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame with exactly two columns:
      - Column 0 (str): Category labels (e.g. "Don't care", "Yes", …).
      - Column 1 (numeric): Values to plot.
    Rows are displayed left-to-right.
output_path : str
    File path for the saved image (PNG/JPEG).
width : int
    Target image width in pixels. Defaults to 600.
height : int
    Target image height in pixels. Auto-sized when None.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
title : str
    Bold title text (supports wrapping over 2 lines).
subtitle : str
    Lighter subtitle rendered below the title.
color : str
    Hex color for the bars.
bar_padding : float
    Fraction of bar slot left as gap between bars (0–1). Default 0.35.
value_suffix : str
    String appended to value labels and axis ticks (e.g. "%" or "x").
scale_text : bool
    Whether to scale fonts proportionally with image size.
show_percentages : bool
    If True, value labels show percentages (e.g., '25.0%').
```

---

### `plot_bubble_matrix_chart`

**Description:**
Plots a bubble matrix chart where bubble sizes are proportional to values.

The chart displays a grid of circles whose area encodes the numeric value
at each (row, column) intersection.  A continuous colour gradient is
applied so that the bubble with the smallest value gets ``start_color``
and the bubble with the largest value gets ``end_color``.  Column
headers sit at the top; row category labels are left-aligned to the
left of the grid.  Title and subtitle are flush-left-aligned with the
category labels.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame where the first column contains row category labels and
    every subsequent column is a numeric series whose header becomes a
    column label.  Values determine bubble size and colour intensity.
output_path : str
    File path for the saved image (PNG/JPEG).
width : int
    Target image width in pixels.  Defaults to 1000.
height : int
    Target image height in pixels.  Defaults to 700.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
title : str
    Bold title text drawn above the chart.
subtitle : str
    Lighter subtitle rendered below the title.
bg_color : str
    Hex background color.
start_color : str
    Hex colour for the lowest-value bubble (gradient start).
    Defaults to ``config.DEFAULT_START_COLOR``.
end_color : str
    Hex colour for the highest-value bubble (gradient end).
    Defaults to ``config.DEFAULT_END_COLOR``.
show_values : bool
    If True (default), numeric values are printed inside each bubble.
    Set to False to hide them.
value_suffix : str
    String appended to displayed value labels (e.g. "%" or "x").
scale_text : bool
    Whether to scale fonts proportionally with image size.
```

---

### `plot_dashboard`

**Description:**
Combine multiple clean-charts into a single mosaic image.

This function renders each chart independently and composites them
onto a matplotlib ``subplot_mosaic`` figure.  The user only needs to
supply a list of chart specifications and, optionally, an ASCII
layout string.

**Specific Parameters for this Chart:**
```text
charts : list of tuples
    Each element is a ``(plot_function, kwargs_dict)`` pair.

    *   ``plot_function`` — one of the library's plot functions
        (e.g. ``plot_time_series``, ``plot_barh_chart``, …).
    *   ``kwargs_dict`` — keyword arguments forwarded to that
        function.  ``output_path`` is managed automatically and
        should **not** be included.

    Example::

        charts = [
            (plot_time_series,        {"data": df1, "title": "Sales"}),
            (plot_barh_chart,         {"data": df2, "title": "Top Items"}),
            (plot_donut_chart,        {"data": df3, "title": "Share"}),
            (plot_stacked_bar_chart,  {"data": df4, "title": "Breakdown"}),
        ]

layout : str or None
    An ASCII mosaic string describing how the charts are arranged.
    Each unique letter maps to one chart, in the order the letters
    first appear (left-to-right, top-to-bottom).

    Examples::

        # 2×2 grid (default for 4 charts)
        layout = "AB\nCD"

        # first chart spans entire top row
        layout = "AA\nBC"

        # 1 row, 3 columns
        layout = "ABC"

    If ``None``, charts are placed in an auto-generated grid that
    is roughly square.

title : str or None
    Optional dashboard title rendered above the mosaic.
subtitle : str or None
    Optional subtitle rendered below the title.
output_path : str or None
    File path to save the final image.  If ``None``, the image is
    displayed inline (Jupyter) or via ``plt.show()``.
width : int
    Final image width in pixels (default 1400).
height : int or None
    Final image height in pixels.  When ``None``, height is derived
    from the layout proportions and *width*.
padding : float
    Fractional space between sub-charts (0–0.5).  Default 0.02.
```

---

### `plot_donut_chart`

**Description:**
Plots a donut chart in the Economist style.

The chart features:
  - Cream-gray background matching the Economist palette.
  - Donut wedges with a gradient colour palette.
  - Exterior callout lines connecting each wedge to its label.
  - Labels show category name and value, positioned left/right of the donut.
  - An optional bold center label inside the hole.
  - Bold title and lighter subtitle, left-aligned above the chart.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    Two-column DataFrame (col 0 = labels, col 1 = numeric values).
    If None, a built-in example is used.
output_path : str
    File path for the saved image.
width, height : int
    Target image dimensions in pixels (default 700x700).
title, subtitle : str
    Chart title (bold) and subtitle (lighter).
start_color, end_color : str
    Hex gradient boundaries for wedge colours.
center_label : str
    Bold text inside the hole; use "\n" for line breaks.
value_suffix : str
    Appended to value labels (e.g. "%").
hole_radius : float
    Inner hole as fraction of outer radius (0-1). Default 0.55.
scale_text : bool
    Scale fonts with image size.
start_angle : float
    The angle (in degrees) to start drawing the first wedge. Default 90.0 (12 o'clock).
donut_radius : float
    The outer radius of the donut as a fraction of the available chart height (max 0.4, default 0.4).
show_percentages : bool
    If True, callout labels show percentages (e.g., '25.0%') instead of raw values.
```

---

### `plot_dumbbell_chart`

**Description:**
Plots a horizontal dumbbell (range dot) chart in the Economist style.

Each category row displays two dots connected by a horizontal line,
representing two values (e.g. two time periods, before/after, etc.).
The visual style matches the Economist's editorial chart language:
cream-gray background, top-side x-axis ticks, left-aligned category
labels, vertical gridlines, and a legend with colored dots.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame with exactly three columns:
      - Column 0 (str): Category labels (e.g. country names).
      - Column 1 (numeric): Start/first values (left dot).
      - Column 2 (numeric): End/second values (right dot).
    Rows are displayed top-to-bottom in the order they appear.
    If None, a built-in GDP-by-country example is used.
output_path : str or None
    File path for the saved image (PNG/JPEG).  If None, the chart
    is displayed inline (Jupyter) or via plt.show().
width : int
    Target image width in pixels. Defaults to 600.
height : int
    Target image height in pixels. Auto-sized when None.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
    Overrides explicit width/height when supplied.
title : str
    Bold title text (supports wrapping over 2 lines).
subtitle : str
    Lighter subtitle rendered below the title.
bg_color : str
    Background hex color.  Defaults to the Economist cream.
start_color : str
    Hex color for the first-series dots (column 1). Default pink-red.
end_color : str
    Hex color for the second-series dots (column 2). Default blue.
connector_color : str
    Hex color for the line connecting the two dots. Default muted blue-gray.
dot_size : float or None
    Marker size (matplotlib scatter 's' parameter).  If None, the
    size is auto-scaled based on image dimensions and row count.
value_suffix : str
    String appended to axis tick labels (e.g. "%" or "x").
scale_text : bool
    Whether to scale fonts proportionally with image size.
show_values : bool
    If True, numeric value labels are drawn next to each dot.
_fixed_scale : float or None
    Internal: override for font/margin scaling (used by dashboard).
_fixed_margin_px : float or None
    Internal: override for outer margin in pixels (used by dashboard).
```

---

### `plot_geofacet`

Visualize geographic data using a grid that roughly approximates the physical map.

Parameters:
-----------
data : pd.DataFrame
    DataFrame containing state abbreviations and numeric values.
state_col : str, optional
    Column name containing location abbreviations (e.g. "CA", "NY" or "LON", "SCT"). Auto-detected as the first column if None.
value_col : str, optional
    Column name containing the numeric values to map. Auto-detected as the second column if None.
layout : str, default="us"
    The grid layout to use. (Currently supports "us" and "uk").
display_type : str, default="text"
    The style of the state cells: "text" (heatmap), "donut", or "bar".
max_value : float, default=100.0
    The maximum value used for scaling progress rings and bars.
color : str, optional
    Base color for chart elements. If None, uses config defaults.
bg_color : str, optional
    Canvas background color. If None, uses config defaults.
start_color : str, optional
    Start color for the heatmap interpolation gradient.
end_color : str, optional
    End color for the heatmap interpolation gradient.
missing_color : str, default="#e0e0e0"
    Color to use for states that have no data.
title : str, optional
    Bold title text.
subtitle : str, optional
    Subtitle below the title.
output_path : str, optional
    File path to save the image. Displays inline when None.
width : int, optional
    Target image width in pixels.
height : int, optional
    Target image height in pixels.
aspect_ratio : str, optional
    Forces a specific aspect ratio.
value_suffix : str, default=""
    Suffix appended to the displayed value (e.g. "%").
scale_text : bool, default=True
    Scale fonts proportionally to the overall image width.

---

### `plot_grouped_barh_chart`

**Description:**
Plots a grouped horizontal bar chart in the Economist style.

Each category occupies a horizontal "lane" that contains one bar per
numeric series.  Bars within a group are stacked vertically (top series
first) so that the visual order matches the legend.

The chart inherits the same design language as ``plot_barh_chart``:
cream-gray background, top-side x-axis ticks, left-aligned category
labels, vertical gridlines, and a short red accent rule above the
title.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame whose **first column** contains category labels (str)
    and every subsequent column contains numeric values for one series.
    Rows are displayed top-to-bottom in DataFrame order.
    If None, a built-in example dataset is used.
output_path : str
    File path for the saved image (PNG/JPEG).
width : int
    Target image width in pixels. Defaults to 600.
height : int
    Target image height in pixels.  Auto-sized when None.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
    Overrides explicit width/height when supplied.
title : str
    Bold title text (supports wrapping over 2 lines).
subtitle : str
    Lighter subtitle rendered below the title.
start_color : str
    Hex color for the first series gradient boundary.
    Defaults to Economist red "#e3120b".
end_color : str
    Hex color for the last series gradient boundary.
    Defaults to a light salmon "#f5a8a2".
bar_padding : float
    Fraction of a single bar slot left as whitespace (0–1). Default 0.30.
group_padding : float
    Fraction of the group height used as spacing between groups (0–1).
    Default 0.45.
value_suffix : str
    String appended to axis tick labels (e.g. "%" or "x").
bar_labels : str
    Controls labels drawn on each bar.  One of:
      - ``"none"``  – no bar labels (default).
      - ``"value"`` – numeric value only (e.g. ``"520"``).
      - ``"name"``  – series/column name only (e.g. ``"Sales"``).
      - ``"both"``  – column name + value (e.g. ``"Sales: 520"``).
group_comments : list[dict] or None
    Per-group annotations rendered in the label region.  Each dict
    may contain any combination of:
      - ``"heading"``    – bold heading text.
      - ``"subtitle"``   – lighter descriptive text below the heading.
      - ``"big_number"`` – prominent large bold metric (e.g. ``"1.8×"``).
    The list length must match the number of categories.  Any key
    may be omitted for a given group — only provided fields are
    rendered.  When supplied, the default category labels are
    replaced by these structured comment blocks.
group_separators : bool
    When True, draws thin horizontal lines between adjacent groups
    to visually separate them.  Default False.
scale_text : bool
    Whether to scale fonts proportionally with image size.
```

---

### `plot_insight_card`

**Description:**
Plots a solid color card with large stylized text and an optional bottom image graphic.

**Specific Parameters for this Chart:**
```text
text : str
    The main insight or summary text to display.
subtext : str, optional
    Secondary text displayed below the main text in a smaller, lighter font.
image_path : str, optional
    Path to a raster image (PNG/JPG) to render at the bottom of the card. 
    (SVG reading is not natively supported by Matplotlib without external dependencies).
output_path : str
    File path for the saved image.
width : int
    Target image width in pixels.
height : int
    Target image height in pixels.
aspect_ratio : str
    One of "vertical"/"1:2", "card"/"4:5", "portrait"/"3:4", "square"/"1:1", "landscape"/"2:1". Defaults to "landscape".
bg_color : str
    Hex color for the card background. Defaults to config.DEFAULT_COLOR_POP.
text_color : str
    Hex color for the text. Defaults to config.INVERTED_TEXT_COLOR.
scale_text : bool
    Whether to scale fonts proportionally with image size.
```

---

### `plot_stacked_bar_chart`

**Description:**
Plots a stacked horizontal bar chart in the Economist style.

Each category occupies a horizontal "lane" that contains a single bar.
The series are stacked horizontally from left to right within that bar.

The chart inherits the same design language as ``plot_barh_chart``:
cream-gray background, top-side x-axis ticks, left-aligned category
labels, vertical gridlines, and a short red accent rule above the
title.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame whose **first column** contains category labels (str)
    and every subsequent column contains numeric values for one series.
    Rows are displayed top-to-bottom in DataFrame order.
    If None, a built-in example dataset is used.
output_path : str
    File path for the saved image (PNG/JPEG).
width : int
    Target image width in pixels. Defaults to 600.
height : int
    Target image height in pixels.  Auto-sized when None.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
    Overrides explicit width/height when supplied.
title : str
    Bold title text (supports wrapping over 2 lines).
subtitle : str
    Lighter subtitle rendered below the title.
colors : list of str, optional
    List of hex colors to use for the stacked series.
    Defaults to config.DEFAULT_COLORS_LIST.
start_color : str, optional
    Hex color for the first series gradient boundary.
    If provided along with end_color, overrides `colors`.
end_color : str, optional
    Hex color for the last series gradient boundary.
    If provided along with start_color, overrides `colors`.
bar_padding : float
    Fraction of a single bar slot left as whitespace (0-1). Default 0.30.
value_suffix : str
    String appended to axis tick labels (e.g. "%" or "x").
bar_labels : str
    Controls labels drawn on each bar.  One of:
      - ``"none"``  - no bar labels (default).
      - ``"value"`` - numeric value only (e.g. ``"520"``).
      - ``"name"``  - series/column name only (e.g. ``"Sales"``).
      - ``"both"``  - column name + value (e.g. ``"Sales: 520"``).
scale_text : bool
    Whether to scale fonts proportionally with image size.
show_percentages : bool
    If True, value labels show percentages (e.g., '25.0%') instead of raw values.
```

---

### `plot_table`

Plots an Economist-style data table using Matplotlib primitives.
Supports multiline wrapping for text and dynamic row heights.

Parameters:
-----------
data : pandas.DataFrame or list
    The tabular data to plot. Supports MultiIndex columns and rows for grouping.
output_path : str
    The file path to save the generated image (e.g., 'table.png'). If None, displays inline.
width : int
    The width of the generated image in pixels.
height : int
    The height of the generated image in pixels. Computed dynamically if not provided.
aspect_ratio : str or float
    The desired aspect ratio (e.g., 'landscape', 'square', 'vertical', '2:1').
title : str
    The main title of the table, displayed at the top left.
subtitle : str
    The secondary title of the table, displayed below the main title.
bg_color : str
    The hex color code for the background of the image. Defaults to theme config.
columns : list of dict
    Column-specific configurations. E.g., [{"align": "right", "width_pct": 0.2, "header_align": "left"}].
cellStyles : dict
    Styling applied to specific cells by (row_idx, col_idx) tuple. E.g., {(0, 1): {"color": "#ff0000", "weight": "bold"}}.
highlightRules : list of dict
    Rules to automatically highlight cells based on conditions. The 'col' key can optionally restrict the rule to a specific data column index (0-indexed data column).
    Supported 'condition' types:
    1. "positive-negative": Highlights positive and negative numeric values.
       Example: {"col": 1, "condition": "positive-negative", "positive_color": "#b2ccb9", "negative_color": "#ffc4b2"}
    2. range, list, or tuple: Highlights numeric values within the specific range (inclusive for list/tuple, exclusive upper bound for range).
       Example: {"condition": [10, 100], "color": "#f1e5a1"}
    3. "range": Acts as a color scale (heatmap) diverging from zero. Uses `max_color` for the maximum positive value and `min_color` for the minimum negative value. Intensity scales to zero.
       Example: {"condition": "range", "max_color": "#b2ccb9", "min_color": "#ffc4b2"}
    4. callable: A custom function `func(val, row_idx, col_idx)` that returns a hex color string or None.
       Example: {"condition": lambda v, r, c: "#ff0000" if isinstance(v, str) and "Error" in v else None}
    Table-level formatting options:
    - showPills (bool): Whether to draw pills for values if supported (default True).
    - rowGroupDivider (bool): Whether to draw lines between row groups (default True).
    - rowGroupSpacing (float): Vertical spacing multiplier for row groups.
    - columnGroupDivider (bool): Whether to draw vertical lines between column groups (default False).
    - columnGroupSpacing (float): Horizontal spacing multiplier for column groups.
    - alternateRowHighlight (bool): Alternating row background colors (default False).
    - alternateRowBgColor (str): Hex color for alternating row background.
    - rowSpacing (float): Global row vertical spacing multiplier.
    - columnSpacing (float): Global column horizontal padding multiplier.
    - rowLabelWidthPct (float): The width percentage reserved for the row labels column.
scale_text : bool
    Whether to automatically scale font sizes relative to image dimensions.
_fixed_scale : float
    Internal parameter to override auto-scaling.
_fixed_margin_px : int
    Internal parameter to override margin pixels.

---

### `plot_time_series`

    Plots a time-series line chart in the exact styling of the provided Economist chart.
    Automatically identifies the date/time column and value columns from the data.
    Optionally generates a color gradient between start_color and end_color.
    Allows user to select X-axis label frequency and input custom title and subtitle.
    
    Parameters:
        data (pd.DataFrame): DataFrame with time series columns.
                             If None, the default reconstructed dataset will be used.
        output_path (str): File path to save the generated image.
        width (int): Target width of the image in pixels.
        height (int): Target height of the image in pixels.
        aspect_ratio (str): Aspect ratio: "square" (or "1:1"), "landscape" (or "2:1"), "vertical" (or "1:2").
                            If provided, dynamically sets width and height.
        title (str): Custom title for the chart. Defaults to empty string.
        subtitle (str): Custom subtitle for the chart. Defaults to empty string.
        start_color (str): Hex color code for the first line series gradient boundary.
        end_color (str): Hex color code for the last line series gradient boundary.
        label_frequency (str): X-axis label frequency: "year", "quarter", "month", "week", "day", "hour", "minute", "second".
        markers (bool or str): Show data-point markers on lines.
            - False: no markers (default).
            - True: circle markers ("o").
            - str: any valid matplotlib marker string (e.g. "o", "s", "D", "^").
        line_labels (str): Controls inline text labels drawn near line endpoints.
            - "name": series/column name only (default).
            - "value": last numeric value only.
            - "both": column name + last value.
            - "none": no inline labels.
        value_suffix (str): String appended to value labels (e.g. "%" or "x").
        smooth (bool): If True, draws smooth cubic-spline curves through the
            data points instead of straight line segments.  Requires scipy.
        scale_text (bool): Whether to scale fonts and line weights proportionally.
        vlines: Vertical reference lines drawn on specific dates.
            Accepts any of the following forms:
            - A single date string or datetime:  "2023-06-15"
            - A dict with "date" (required), optional "color", "linewidth",
              "linestyle", "label", "paragraph", and "paragraph_y"::

                {"date": "2023-06-15", "color": "#e3120b",
                 "label": "Launch",
                 "paragraph": "Product v2.0 launched
with new pricing model"}

              ``paragraph`` renders a multi-line annotation next to the
              vertical line inside a rounded semi-transparent box.
              ``paragraph_y`` (float 0-1, default 0.85) controls the
              vertical placement as an axis-fraction.
            - A list mixing any of the above.
        highlight_ranges: Shaded time-range rectangles.
            Accepts any of the following forms:
            - A tuple/list of two dates:  ("2022-01-01", "2023-01-01")
            - A dict with "start" and "end" (required), optional "color",
              "alpha", "label", "paragraph", and "paragraph_y"::

                {"start": "2022-01-01", "end": "2023-01-01",
                 "color": "#1f77b4", "alpha": 0.15,
                 "label": "Recession",
                 "paragraph": "GDP contracted for
two consecutive quarters"}

              ``label`` is a bold heading rendered at the top of the range.
              ``paragraph`` is a multi-line annotation rendered inside the
              shaded region in a rounded box.  ``paragraph_y`` (float 0-1,
              default 0.85) controls vertical placement.
            - A list mixing any of the above.
        callouts: Annotate specific data points with a dot, leader line,
            and a multi-line text box.  The value is looked up from the
            data automatically by snapping to the nearest date.
            Accepts a single dict or a list of dicts.  Each dict has:

            - ``date`` *(required)* — date string or datetime.  The
              nearest date in the data is used.
            - ``series`` — column name to read the y-value from.
              Defaults to the first value column.
            - ``text`` *(required)* — annotation text (use ``
`` for
              multiple lines).
            - ``color`` — dot & border colour (default ``"#e3120b"``).
            - ``text_x`` — horizontal offset of the text box from the
              data point, in axis-data units (positive = right).  If not
              given, defaults to a small rightward nudge.
            - ``text_y`` — vertical offset in data units (positive = up).
              If not given, defaults to a small upward nudge.
            - ``ha`` — horizontal alignment of the text box relative to
              the leader-line endpoint: ``"left"`` (default), ``"center"``,
              or ``"right"``.

            Example::

                {"date": "2024-01-01",
                 "text": "ATH reached
14.2% market share",
                 "color": "#e3120b"}
    

---

### `plot_waffle_chart`

**Description:**
Plots a multi-category waffle chart (10x10 dot grids) in the Economist style.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame with two or three columns:
      - Column 0 (str): Label/heading text (if 3 columns) or Category description text (if 2 columns).
      - Column 1 (str/numeric): Category description text (if 3 columns) or Percentage values (if 2 columns).
      - Column 2 (numeric): Percentage values (if 3 columns).
output_path : str
    File path for the saved image.
width : int
    Target image width in pixels. Defaults to max(800, n * 180).
height : int
    Target image height in pixels. Defaults to 450.
aspect_ratio : str
    One of "square"/"1:1", "landscape"/"2:1", "vertical"/"1:2".
    Overrides explicit width/height when supplied.
title : str
    Bold title text.
subtitle : str
    Lighter subtitle rendered below the title.
color : str
    Hex color for the filled dots.
inactive_color : str
    Hex color for the unfilled dots.
value_suffix : str
    String appended to value labels (e.g. "%").
scale_text : bool
    Whether to scale fonts proportionally with image size.
```

---



### `plot_bubble_scatter_chart`

**Description:**
Plots a 3-variable bubble scatter plot in the Economist style.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    - 3 columns: [X, Y, Size]
    - 4 columns: [Label, X, Y, Size]
    If None, a built-in Country Income vs Life Expectancy dataset is used.
output_path : str or None
    File path for the saved image.
width, height : int or None
    Target image dimensions in pixels (default 750x550).
aspect_ratio : str or None
    "square", "landscape", "vertical", "1:1", "2:1", "1:2".
title, subtitle : str or None
    Header title (bold) and subtitle text.
bg_color : str or None
    Hex background color. Defaults to Economist cream.
start_color, end_color : str or None
    Hex colors for bubble palette interpolation if `color` is None.
color : str or None
    Single color for all bubbles.
min_bubble_size, max_bubble_size : float
    Min and max bubble marker area size in points^2. Defaults to 60 and 600.
alpha : float
    Transparency of scatter points (0.0 to 1.0).
x_label, y_label : str or None
    Labels for X and Y axes.
x_suffix, y_suffix, size_suffix : str
    Suffix strings for annotations (e.g., "$", "%", "k").
show_values : bool
    If True, annotates bubbles with their size values.
show_labels : bool
    If True, annotates bubbles with label strings.
axes_origin : tuple or None
    Custom origin for axes.
show_grid : bool
    Whether to show grid lines.
scale_text : bool
    Whether to scale font sizes proportionally with image dimensions.
```

---

### `plot_grouped_scatter_chart`

**Description:**
Plots a grouped or quadrant-mapped scatter plot in the Economist style.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    - Categorical mode: DataFrame with 3 or 4 columns [Label, X, Y, Category] or [X, Y, Category].
    - Quadrant mode: DataFrame with [Label, X, Y] or [X, Y].
    If None, a built-in Global Economic Performance dataset is used.
output_path : str or None
    File path for the saved image.
width, height : int or None
    Target image dimensions in pixels (default 750x550).
aspect_ratio : str or None
    "square", "landscape", "vertical", "1:1", "2:1", "1:2".
title, subtitle : str or None
    Header title (bold) and subtitle text.
bg_color : str or None
    Hex background color. Defaults to Economist cream.
start_color, end_color : str or None
    Hex colors for group palette interpolation.
colors : list of str or None
    Explicit list of hex colors for categories/quadrants.
dot_size : float
    Marker size (area in points^2).
alpha : float
    Transparency of scatter points (0.0 to 1.0).
x_label, y_label : str or None
    Labels for X and Y axes.
x_suffix, y_suffix : str
    Suffix strings for annotations.
group_by : str or None
    "category" (default if category column exists) or "quadrant".
x_threshold, y_threshold : float or None
    Threshold lines for quadrant division. Defaults to median/mean if None.
quadrant_labels : list of 4 str or None
    Labels for top-right (Q1), top-left (Q2), bottom-left (Q3), bottom-right (Q4).
show_labels : bool
    If True, annotates scatter points with label strings.
show_threshold_lines : bool
    If True, plots the x and y threshold lines in quadrant mode.
axes_origin : tuple or None
    Custom origin for axes.
show_grid : bool
    Whether to show grid lines.
scale_text : bool
    Whether to scale font sizes proportionally with image dimensions.
```

---

### `plot_scatter_chart`

**Description:**
Plots a 2D scatter plot in the Economist style.

**Specific Parameters for this Chart:**
```text
data : pd.DataFrame or None
    DataFrame with 2 or 3 columns:
      - If 2 columns: Col 0 = X values (numeric), Col 1 = Y values (numeric).
      - If 3 columns: Col 0 = Labels (str), Col 1 = X values, Col 2 = Y values.
    If None, a built-in R&D Spend vs Patent Applications dataset is used.
output_path : str or None
    File path for the saved image.
width, height : int or None
    Target image dimensions in pixels (default 700x500).
aspect_ratio : str or None
    "square", "landscape", "vertical", "1:1", "2:1", "1:2".
title, subtitle : str or None
    Header title (bold) and subtitle text.
bg_color : str or None
    Hex background color. Defaults to Economist cream (#f4f3f0).
color : str
    Hex color for scatter dots. Defaults to config.DEFAULT_COLOR (#000000).
dot_size : float
    Marker size (area in points^2). Defaults to 80.
alpha : float
    Transparency of scatter points (0.0 to 1.0).
x_label, y_label : str or None
    Labels for X and Y axes.
x_suffix, y_suffix : str
    Suffix strings for axis tick annotations (e.g., "$", "%", "k").
show_labels : bool
    If True, annotates scatter points with label strings.
show_trendline : bool
    If True, plots a linear regression trend line.
trendline_color : str or None
    Hex color for the trend line (defaults to Economist blue #2323FF).
axes_origin : tuple or None
    Custom origin for axes.
show_grid : bool
    Whether to show grid lines.
scale_text : bool
    Whether to scale font sizes proportionally with image dimensions.
```

---
