"""
This module uses data from World Bank WDI, World Bank Quarterly Public
Sector Debt (QPSD) database, the IMF, and UN ILO to find values for
parameters for the OG-ZAF model that rely on macro data for calibration.
"""
# imports
import pandas as pd
import requests
import datetime
from io import StringIO
from pathlib import Path
[docs]
def _fetch_wb_data(indicators, country_iso, start_year, end_year, source):
"""
Fetch a set of World Bank indicators and return a single DataFrame.
Args:
indicators (dict): mapping of human-readable labels to indicator codes
country_iso (str): ISO country code
start_year (int): first year to request
end_year (int): last year to request
source (int): World Bank source ID
Returns:
pandas.DataFrame: DataFrame indexed by year/quarter label
"""
if source == 2:
date_range = f"{start_year}:{end_year}"
elif source == 20:
date_range = f"{start_year}Q1:{end_year}Q4"
else:
raise ValueError(f"Unsupported World Bank source: {source}")
data_frames = []
for label, indicator_code in indicators.items():
response = requests.get(
(
"https://api.worldbank.org/v2/country/"
f"{country_iso}/indicator/{indicator_code}"
),
params={
"date": date_range,
"source": source,
"format": "json",
"per_page": 10000,
},
)
response.raise_for_status()
try:
payload = response.json()
except ValueError as exc:
raise ValueError(
f"Malformed World Bank response for {indicator_code}"
) from exc
if (
not isinstance(payload, list)
or len(payload) < 2
or not isinstance(payload[1], list)
or not payload[1]
):
raise ValueError(
f"Empty or malformed World Bank response for {indicator_code}"
)
series_data = {}
for row in payload[1]:
date = row.get("date")
if date is None:
continue
series_data[date] = row.get("value")
if not series_data:
raise ValueError(
"No dated observations in World Bank response for "
f"{indicator_code}"
)
series = pd.Series(series_data, name=label)
series = pd.to_numeric(series, errors="coerce")
data_frames.append(series.to_frame())
data = pd.concat(data_frames, axis=1)
data.index.name = "year"
# Preserve descending time order used by the existing pct_change(-1) logic.
data = data.sort_index(ascending=False)
return data
[docs]
def _get_imf_macro_params(
country_iso,
target_year,
data_path=None,
):
"""
Fetch IMF GFS data and compute alpha_T and alpha_G.
Args:
country_iso (str): ISO alpha-3 country code
target_year (int): preferred calibration year
data_path (str | Path | None): optional path to save IMF CSV data
Returns:
dict: IMF-derived macro parameters
"""
required_indicators = {"G2_T", "G24_T", "G27_T", "G271_T"}
data_path = Path(data_path) if data_path is not None else None
response = requests.get(
(
"https://api.imf.org/external/sdmx/3.0/data/dataflow/"
f"IMF.STA/GFS_SOO/12.0.0/"
f"{country_iso}.S1311.G2M.*.POGDP_PT.A"
),
timeout=30,
)
response.raise_for_status()
try:
payload = response.json()
data = payload["data"]
structure = data["structures"][0]
data_set = data["dataSets"][0]
series_dimensions = structure["dimensions"]["series"]
observation_years = [
value.get("id", value.get("value"))
for value in structure["dimensions"]["observation"][0]["values"]
]
except (ValueError, KeyError, IndexError, TypeError) as exc:
raise ValueError(
"Empty or malformed IMF response for GFS_SOO"
) from exc
records = []
for series_key, series in data_set["series"].items():
dimension_indexes = [int(idx) for idx in series_key.split(":")]
labels = {
dim["id"]: dim["values"][idx]["id"]
for dim, idx in zip(series_dimensions, dimension_indexes)
}
indicator = labels.get("INDICATOR")
if indicator not in required_indicators:
continue
for observation_key, observation in series.get(
"observations", {}
).items():
value = observation[0]
if value is None:
continue
records.append(
{
"year": observation_years[int(observation_key)],
"indicator": indicator,
"value": float(value),
"country_iso": country_iso,
"sector": "S1311",
"dataset": "IMF.STA:GFS_SOO(12.0.0)",
}
)
imf_data = pd.DataFrame(records)
if imf_data.empty:
raise ValueError("Empty or malformed IMF response for GFS_SOO")
if data_path is not None:
data_path.parent.mkdir(parents=True, exist_ok=True)
imf_data.sort_values(["indicator", "year"]).to_csv(
data_path, index=False
)
print(f"IMF data saved to {data_path}")
imf_data["year"] = pd.to_numeric(imf_data["year"], errors="coerce")
imf_data["value"] = pd.to_numeric(imf_data["value"], errors="coerce")
imf_data = imf_data.dropna(subset=["year", "value"])
available = (
imf_data.pivot_table(
index="year", columns="indicator", values="value", aggfunc="first"
)
.sort_index()
.dropna(subset=sorted(required_indicators))
)
available = available.loc[available.index <= int(target_year)]
if available.empty:
raise ValueError(
f"No complete IMF data available for {country_iso} "
f"up to {target_year}"
)
selected_year = (
int(target_year)
if int(target_year) in available.index
else int(available.index.max())
)
if selected_year != int(target_year):
print(
f"Warning: No IMF data for {target_year}. "
f"Using last available year: {selected_year}"
)
values = available.loc[selected_year]
return {
"alpha_T": [(values["G27_T"] - values["G271_T"]) / 100],
"alpha_G": [
(values["G2_T"] - values["G24_T"] - values["G27_T"]) / 100
],
}
[docs]
def get_macro_params(
data_start_date=datetime.datetime(1947, 1, 1),
data_end_date=datetime.datetime(2024, 12, 31),
country_iso="ZAF",
update_from_api=False,
imf_data_year=None,
imf_data_path=None,
):
"""
Compute values of parameters that are derived from macro data
Args:
data_start_date (datetime): start date for data
data_end_date (datetime): end date for data
country_iso (str): ISO code for country
imf_data_year (int | None): IMF target year override. Defaults to
data_end_date.year when None.
imf_data_path (str | Path | None): optional path to save IMF CSV data
Returns:
macro_parameters (dict): dictionary of parameter values
Note:
Only parameters whose documented source is a live API AND which
are not curated for internal consistency are refreshed here:
gamma (ILOSTAT labour share) and alpha_T (IMF GFS non-interest
transfers). Everything else is a curated packaged value and is
deliberately NOT updated here, because a refresh would clobber a
deliberately-chosen value: g_y_annual (a forward-looking long-run
productivity growth, not the stagnant realized series), alpha_G
(pinned to fiscal-consistency with the debt target, not the raw
GFS figure), the debt block (initial_debt_ratio,
initial_foreign_debt_ratio, zeta_D — National Treasury figures,
not the wider-perimeter World Bank QPSD), and the r_gov wedge
(r_gov_scale from LMWW, r_gov_shift re-anchored to SA's effective
rate and holding the debt-elastic premium's recentering). Those
values live in ogzaf_default_parameters.json and are documented
in docs/book/content/calibration/macro.md.
"""
# initialize a dictionary of parameters
macro_parameters = {}
# NOTE: g_y_annual is no longer pulled from the World Bank. It is a
# curated long-run productivity growth (0.014, PWT GDP per person engaged
# 1994-2019); the stagnant recent years enter through the Z path in
# ogzaf/productivity.py, not through g_y. Likewise the debt block
# (initial_debt_ratio, initial_foreign_debt_ratio, zeta_D) is not pulled:
# the World Bank QPSD measures a wider (general-government) perimeter
# than the National Treasury national-government figure the model
# tracks. Both live in the packaged ogzaf_default_parameters.json; see
# docs/book/content/calibration/macro.md.
"""
Retrieve labour share data from the United Nations ILOSTAT Data API
(see https://rshiny.ilo.org/dataexplorer9/?lang=en)
The series code is SDG_1041_NOC_RT_A (capital share)
Labor share (gamma) = 1 - capital share
If this fails we will not update gamma in 'default_parameters.json'
"""
if update_from_api:
try:
target = (
"https://rplumber.ilo.org/data/indicator/"
+ "?id=SDG_1041_NOC_RT_A"
+ "&ref_area="
+ str(country_iso)
+ "&timefrom="
+ str(data_start_date.year)
+ "&timeto="
+ str(data_end_date.year)
+ "&type=both&format=.csv"
)
# Add headers
headers = {
"User-Agent": (
"Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
"AppleWebKit/537.36 (KHTML, like Gecko) "
"Chrome/91.0.4472.124 Safari/537.36"
)
}
print("Attempting to update gamma from ILOSTAT")
response = requests.get(target, headers=headers)
if response.status_code != 200:
print(f"Error: Received status code {response.status_code}")
else:
print("Request successful.")
csv_content = StringIO(response.text)
df_temp = pd.read_csv(csv_content)
ilo_data = df_temp[["time", "obs_value"]]
# find gamma, capital's share of income
macro_parameters["gamma"] = [
1
- (
(
ilo_data.loc[
ilo_data["time"] == data_end_date.year, "obs_value"
].squeeze()
)
/ 100
)
]
print(
f"gamma updated from ILOSTAT API: {macro_parameters['gamma']}"
)
except Exception:
print("Failed to retrieve data from ILOSTAT")
print("Will not update gamma")
else:
print("Not updating from ILOSTAT API")
"""
Calibrate parameters from IMF data
"""
if update_from_api:
try:
imf_year = (
data_end_date.year if imf_data_year is None else imf_data_year
)
imf_params = _get_imf_macro_params(
country_iso,
imf_year,
data_path=imf_data_path,
)
# alpha_T (non-interest transfers) keeps its documented GFS value.
# alpha_G is NOT taken from GFS: it is curated (~0.19), pinned to
# the level that makes the government budget consistent with the
# steady-state debt target (see the fiscal-consistency section of
# docs/book/content/calibration/macro.md). Refreshing it from GFS
# would restore the raw ~0.23-0.27 figure and break that
# consistency, so we drop it here.
macro_parameters["alpha_T"] = imf_params["alpha_T"]
print(
f"alpha_T updated from IMF data: {macro_parameters['alpha_T']}"
)
except Exception:
print("Failed to retrieve data from IMF")
print("Will not update alpha_T")
# NOTE: the r_gov wedge (r_gov_scale, r_gov_shift) is
# intentionally no longer recomputed here. The Li, Magud,
# Werner, Witte (2021) inversion (see
# https://github.com/EAPD-DRB/OG-ZAF/issues/22 and the macro
# calibration chapter) is deterministic — it contains no live
# South African data — and the packaged r_gov_shift is now
# recentered so the debt-elastic sovereign premium
# (r_gov_DY, r_gov_DY2) is exactly zero at the steady-state
# debt target. Recomputing the LMWW values here would silently
# undo that recentering. The packaged values live in
# ogzaf_default_parameters.json.
else:
print("Not updating alpha_T")
return macro_parameters