Lagged Oil–Unemployment Chart

A self-contained toolkit that:

• Fetches U.S. unemployment rate (UNRATE) and WTI crude oil price (DCOILWTICO) from FRED
• Stores the series in a local SQLite database (data/fred.db)
• Produces a dual-axis plot of unemployment vs. lagged oil price, with customizable lag, date range, and styling

---

🚀 Quickstart

# Clone the repo
git clone https://github.com/your-org/python_charts.git
cd python_charts

# One-command: install deps, download data, and plot
./startup.sh python scripts/lagged_oil_unrate_chart_styled.py \
    --offset 12 --end 2025-05-31 --extend-years 5

This will:

1. Create (or reuse) a Python 3 virtual environment (venv/)
2. Upgrade pip & setuptools (providing distutils support)
3. Install required packages (offline wheelhouse first, PyPI fallback)
4. Download UNRATE & DCOILWTICO into data/fred.db if missing
5. Generate the chart with a 12-month oil lead, extending the x-axis by 5 years

---

📁 Repository Structure

python_charts/
├── data/
│   └── fred.db                 # Local FRED snapshot (SQLite)
├── scripts/
│   ├── refresh_data.py         # Download and store FRED series
│   ├── lagged_oil_unrate_chart_styled.py  # Plotting script
│   └── pyproject.toml          # Packaging metadata
├── startup.sh                  # Bootstraps venv, deps, data, and runs commands
├── requirements.txt            # Python dependencies
└── README.md                   # This file

---

🛠️ Installation & Setup

1. Ensure you have Python 3.8+ installed on your system.

2. Clone and navigate into the project:

   git clone https://github.com/your-org/python_charts.git
   cd python_charts
   

3. Make the startup script executable:

   chmod +x startup.sh
   

On first run, startup.sh will build the environment, install dependencies, and pull data.

---

⚙️ Usage

Refresh FRED data

./startup.sh python scripts/refresh_data.py

Downloads the full UNRATE and WTI series (from 1948 to today) into data/fred.db.

Generate the chart

# Default 18-month lag
./startup.sh

# Custom lag, range, and extension
./startup.sh python scripts/lagged_oil_unrate_chart_styled.py \
    --offset 6 --start 1980-01-01 --end 2025-05-31 --extend-years 2

Option	Description
--offset	Lag in months (positive = oil leads; negative = oil lags)
--start	Start date (YYYY-MM-DD)
--end	End date (YYYY-MM-DD)
--extend-years	Years to extend the x-axis beyond the end date

---

📝 Details

• Data storage: data/fred.db (SQLite) holds two tables: UNRATE and DCOILWTICO.

• Plot styling:

  • Left y-axis: unemployment rate (%) from 3 to 15%, ticks every 2%.
  • Right y-axis: log scale oil price (USD), doubling ticks from $3 upward.
  • X-axis: years, major tick every 5 years, minor tick every year.

---

📦 Dependencies

Listed in requirements.txt:

pandas>=1.5.0
pandas_datareader>=0.10.0
matplotlib>=3.5.0
lxml>=4.6.0
python-dateutil>=2.8.1

startup.sh also upgrades pip & setuptools to ensure distutils is available.

---

🛡️ Troubleshooting

• ModuleNotFoundError: distutils: resolved automatically by upgrading setuptools in startup.sh.
• Database not found: run ./startup.sh python scripts/refresh_data.py to populate data/fred.db.
• Virtual-env issues: delete venv/ and re-run startup.sh.

---

📄 License

This project is released under the MIT License. See LICENSE for details.