humandev-forecast

humandev-forecast is a reproducible data science package for building a global country-year human-development panel and forecasting 3-year Human Development Index trajectories.

The project combines public indicators from:

• World Bank Indicators API
• WHO Global Health Observatory OData API
• UNDP Human Development Report public downloads

It is built as a portfolio-grade Python package: installable, testable, documented, and runnable from both a CLI and Python notebooks.

Quick Start

python -m pip install -e ".[dev,docs,notebooks]"
humandev fetch --source all
humandev build-panel --start-year 1990 --end-year 2023
humandev train --horizon 3 --target hdi
humandev evaluate
humandev explain

Generated artifacts are written to:

• data/processed/panel.parquet
• data/processed/modeling_dataset.parquet
• models/hdi_forecaster.joblib
• reports/metrics.json
• reports/feature_importance.csv

Python API

from humandev_forecast import DataConfig, build_panel, fetch_sources, make_supervised_panel
from humandev_forecast.modeling import train_forecaster

config = DataConfig(project_dir=".")
raw = fetch_sources(config)
panel = build_panel(raw, config)
dataset = make_supervised_panel(panel, horizon=3)
result = train_forecaster(dataset, config=config)

print(result.model_name)
print(result.metrics)

Data Sources

The package uses public data and keeps raw downloads out of Git:

• World Bank API: socioeconomic and infrastructure indicators.
• WHO GHO API: health indicators such as life expectancy.
• UNDP HDR CSV: HDI, HDI components, inequality, gender, planetary pressure, and population fields.

UNDP public CSV downloads are used by default instead of keyed API access.

Development

python -m pip install -e ".[dev,docs]"
ruff check .
ruff format --check .
pytest
python -m build
mkdocs build --strict

Release

The repo includes GitHub Actions for CI, GitHub Pages docs, and manual TestPyPI/PyPI publishing. Configure trusted publishing on TestPyPI and PyPI before using the release workflow.