Create publication-ready charts from any data source (CSV, JSON, FRED API, or inline data). Supports line, bar, scatter, area-fill, indexed series, annotatio...
---
name: data-chart-builder
description: "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."
---
# 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
| 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
```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](https://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 |
don't have the plugin yet? install it then click "run inline in claude" again.