mirror of
https://github.com/PR0M3TH3AN/python_charts.git
synced 2026-10-27 08:50:39 +00:00
thePR0M3TH3AN
8797ef1d04
Update README.md to reflect new project focus on lagged oil and unemployment charting. Revise installation instructions, quickstart guide, and repository structure. Modify scripts for data fetching and plotting, and add a new SQLite database for storing FRED data. Introduce a startup script to streamline setup and execution.
139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
git clone https://github.com/your-org/python_charts.git
|
||
cd python_charts
|
||
```
|
||
3. **Make** the startup script executable:
|
||
|
||
```bash
|
||
chmod +x startup.sh
|
||
```
|
||
|
||
> On first run, `startup.sh` will build the environment, install dependencies, and pull data.
|
||
|
||
---
|
||
|
||
## ⚙️ Usage
|
||
|
||
### Refresh FRED data
|
||
|
||
```bash
|
||
./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
|
||
|
||
```bash
|
||
# 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`:
|
||
|
||
```text
|
||
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](LICENSE) for details.
|