Installation

Requirements

• Python 3.10 or later

• pandas, numpy, scikit-learn, statsmodels, scipy, matplotlib, openpyxl, PyYAML

Install from PyPI

pip install macroforecast

Optional extras:

pip install 'macroforecast[deep]'
pip install 'macroforecast[xgboost,lightgbm]'
pip install 'macroforecast[tuning]'
pip install 'macroforecast[shap]'
pip install 'macroforecast[all]'

Or pin to a tagged GitHub release directly:

pip install "git+https://github.com/NanyeonK/macroforecast.git@v0.9.0a0"

Install from source (development)

git clone https://github.com/NanyeonK/macroforecast.git
cd macroforecast
pip install -e ".[dev]"

Verify installation

import macroforecast
print(f"macroforecast version: {macroforecast.__version__}")     # 0.9.0a0

Run the test suite:

python -m pytest tests/ -x -q -m "not deep"

Expected: 1318 tests pass / 19 skipped / 4 deselected in ~85 seconds (local core baseline).

Optional dependencies

macroforecast has several optional dependencies for specific features. Install only what you need:

Package	Required for	Install
optuna	Bayesian optimization tuning	pip install optuna
shap	TreeSHAP, KernelSHAP, LinearSHAP importance	pip install shap
lime	LIME local surrogate importance	pip install lime
xgboost	XGBoost model family	pip install xgboost
lightgbm	LightGBM model family	pip install lightgbm
catboost	CatBoost model family	pip install catboost
deep extra (torch)	LSTM / GRU / TCN model families	see [deep] section below

(openpyxl is now a core dependency in v0.6.3+ since FRED-SD Excel workbook loading is a baseline FRED-SD code path.)

Install all optional dependencies at once:

pip install "macroforecast[all] @ git+https://github.com/NanyeonK/macroforecast.git@v0.9.0a0"

All optional dependencies are import-guarded. The package works without them, but the corresponding features will raise ImportError with a clear message when invoked.

The [deep] extra

The lstm, gru, and tcn model families ship behind an opt-in [deep] extra so core installs stay free of a torch dependency:

pip install "macroforecast[deep] @ git+https://github.com/NanyeonK/macroforecast.git@v0.9.0a0"

Without the extra, referencing model_family in {lstm, gru, tcn} at sweep time raises a clear ExecutionError with the install hint.

For CPU-only torch (sufficient unless a GPU sweep is planned):

pip install --index-url https://download.pytorch.org/whl/cpu torch
pip install "macroforecast[deep] @ git+https://github.com/NanyeonK/macroforecast.git@v0.9.0a0"

Core dependencies (automatically installed)

Package	Purpose
pandas	Data handling and DataFrame output
numpy	Numerical computation
scikit-learn	Model families (Ridge, Lasso, RF, etc.), preprocessing, CV
statsmodels	AR models, statistical tests
scipy	Statistical routines and numerical utilities
matplotlib	L7 figure rendering (bar / heatmap / pdp / US choropleth)
openpyxl	FRED-SD Excel workbook loading
PyYAML	Recipe YAML parsing

See also: Researchers: Quickstart