Data Chart Builder

Create publication-ready charts from any data source (CSV, JSON, FRED API, or inline data). Supports line, bar, scatter, area-fill, indexed series, annotations, and multi-series overlays. Use for economic data visualization, time series comparison, trend analysis, gap/shaded region charts, annotated timelines, or any custom plotting task. Triggers on requests for charts, graphs, plots, data visualization, time series comparison, indexed data plots, or annotated economic/social/technical charts.

Build publication-ready charts from CSV, JSON, FRED, or inline data.

Quick Start

python3 scripts/chart_builder.py --config chart.json

Workflow

1. Prepare data or identify source

Options:

• CSV file: Local or URL
• JSON: Inline in config or external file
• FRED: Federal Reserve series ID
• Inline: Direct data array in config

2. Write config JSON

{
  "title": "My Chart Title",
  "series": [
    {
      "csv": "/path/to/data.csv",
      "date_col": "date",
      "value_col": "price",
      "label": "Stock Price",
      "color": "#2E86AB",
      "index": true
    }
  ],
  "output": "/tmp/my_chart.png"
}

3. Generate

python3 scripts/chart_builder.py --config my_chart.json

Config Reference

Top-level fields

Field	Type	Description
title	string	Chart title
series	array	Data series to plot (required)
output	string	Output path (default: /tmp/chart.png)
figsize	[w, h]	Figure size in inches (default: [12, 7])
start_date / end_date	string	Filter range (YYYY-MM-DD)
index_all	bool	Index all series to 100
fill	bool	Shade between first two series
fill_color	string	Fill color (default: red)
fill_alpha	float	Fill opacity (default: 0.15)
hline	number	Draw horizontal reference line
grid	bool	Show grid (default: true)
ylim	[min, max]	Y-axis limits
annotations	array	Vertical event markers

Series fields

Field	Type	Description
label	string	Legend label (required)
csv	string	Path or URL to CSV
json	string	Path to JSON file
fred	string	FRED series ID
data	array	Inline data: [{"date": "...", "value": 100}, ...]
date_col	string	Date column name (default: date)
value_col	string	Value column name (default: value)
type	string	line, bar, scatter
color	string	Hex color
width	number	Line width
style	string	Line style: -, --, -., :
index	bool	Index this series to 100
base_date	string	Index base date (default: first observation)

Annotations

{
  "date": "2008-09-15",
  "label": "Lehman Bankruptcy",
  "position": "top",
  "y": 120,
  "fontsize": 9
}

Examples

Economic comparison (FRED)

{
  "title": "USA: GDP vs Wages (1959 = 100)",
  "series": [
    {"fred": "A939RX0Q048SBEA", "label": "GDP Per Capita", "color": "#2E86AB", "index": true},
    {"fred": "COMPRNFB", "label": "Compensation Per Hour", "color": "#F18F01", "index": true}
  ],
  "start_date": "1959-01-01",
  "end_date": "1985-12-31",
  "fill": true,
  "annotations": [
    {"date": "1971-08-15", "label": "Nixon Shock", "position": "top", "y": 140},
    {"date": "1973-10-01", "label": "Oil Crisis", "position": "bottom", "y": 90}
  ],
  "output": "gdp_wages.png"
}

Stock price vs volume

{
  "title": "AAPL Price vs Volume",
  "series": [
    {"csv": "aapl.csv", "label": "Price", "color": "#2E86AB", "type": "line"},
    {"csv": "aapl.csv", "label": "Volume", "color": "#F18F01", "type": "bar", "value_col": "volume"}
  ],
  "output": "aapl_chart.png"
}

Inline data

{
  "title": "Sales Q1-Q4",
  "series": [
    {
      "label": "Revenue",
      "data": [
        {"date": "2024-01-01", "value": 100},
        {"date": "2024-04-01", "value": 120},
        {"date": "2024-07-01", "value": 140},
        {"date": "2024-10-01", "value": 180}
      ],
      "color": "#2E86AB",
      "type": "bar"
    }
  ],
  "output": "sales.png"
}

Scatter plot

{
  "title": "Height vs Weight",
  "series": [
    {"csv": "patients.csv", "label": "Male", "color": "blue", "type": "scatter", "date_col": "height", "value_col": "weight"},
    {"csv": "patients.csv", "label": "Female", "color": "red", "type": "scatter", "date_col": "height", "value_col": "weight"}
  ]
}

Tips

• Indexing: Use "index": true on each series or "index_all": true globally to compare growth rates on equal footing
• Colors: Use contrasting hex codes. Good pairs: #2E86AB (blue) + #F18F01 (orange), or #C73E1D (red) + #3B1F2B (dark)
• Annotations: Alternate position: "top" and "bottom" to avoid overlap
• Date parsing: Ensure dates are ISO format (YYYY-MM-DD) for reliable parsing
• FRED: Find series IDs at fred.stlouisfed.org

Data Source Flexibility

Source	How to specify	Best for
Local CSV	"csv": "/path/to/file.csv"	Custom datasets
URL CSV	"csv": "https://example.com/data.csv"	API endpoints
FRED	"fred": "GDPC1"	Economic time series
Inline	"data": [...]	Small static datasets