Source code for ogzaf.macro_params

"""
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