Data Chart Builder

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

Series fields

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