Data Chart Builder#

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

Quick Start#

bash

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#

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#

bash

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

Config Reference#

Top-level fields#

FieldTypeDescriptiontitlestringChart titleseriesarrayData series to plot (required)outputstringOutput path (default: /tmp/chart.png)figsize[w, h]Figure size in inches (default: [12, 7])start_date / end_datestringFilter range (YYYY-MM-DD)index_allboolIndex all series to 100fillboolShade between first two seriesfill_colorstringFill color (default: red)fill_alphafloatFill opacity (default: 0.15)hlinenumberDraw horizontal reference linegridboolShow grid (default: true)ylim[min, max]Y-axis limitsannotationsarrayVertical event markers

Series fields#

FieldTypeDescriptionlabelstringLegend label (required)csvstringPath or URL to CSVjsonstringPath to JSON filefredstringFRED series IDdataarrayInline data: [{"date": "...", "value": 100}, ...]``date_colstringDate column name (default: date)value_colstringValue column name (default: value)typestringline, bar, scatter``colorstringHex colorwidthnumberLine widthstylestringLine style: -, --, -., :``indexboolIndex this series to 100base_datestringIndex base date (default: first observation)

Annotations#

json

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

Examples#

Economic comparison (FRED)#

json

{
  "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#

json

{
  "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#

json

{
  "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#

json

{
  "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#

SourceHow to specifyBest forLocal CSV"csv": "/path/to/file.csv"Custom datasetsURL CSV"csv": "https://example.com/data.csv"API endpointsFRED"fred": "GDPC1"Economic time seriesInline"data": [...]Small static datasets