Source code for ogzaf.calibrate

from ogzaf import macro_params, income
from ogzaf import input_output as io
import os
import warnings
import numpy as np
import datetime

# UN M49 code for South Africa, used for every demographic download.
UN_COUNTRY_CODE = "710"
# Last year of UN data read by the demographics. ogcore freezes fertility,
# mortality and immigration at this year forever, so it sets the long-run
# population growth rate: a two-year window froze 2026 rates (g_n_ss about
# +0.42%/yr), while the UN WPP 2024 projection levels South Africa's population
# off this century (g_n_ss about -0.03%/yr with the full window). 2098 is one
# year before the last year in the UN data (ogcore reads final_data_year + 1)
# and within ogcore's start_year + 74 limit.
DEMOG_FINAL_DATA_YEAR = 2098

# Income gradients in demographic rates, from EAPD-DRB/Demographic-Gradients
# (docs/countries/south-africa.md). Each tilt is the slope of the log rate on
# wealth rank (0 = poorest, 1 = richest); ogcore takes the slope per centered
# percentile point, so every tilt is divided by 100. Negative = poorer groups
# have higher rates. ogcore keeps the national rate at each age and only
# tilts it across lifetime-income groups.
# Fertility: total fertility rate by wealth quintile, DHS 2016.
FERT_TILT = -0.5054
# Infant mortality: DHS 2016 (IMR, not U5MR).
INFMORT_TILT = -0.5443
# Adult mortality by age band: mean of the 2001 and 2007 census household-
# deaths tilts (asset-index ranking, all deaths linked; IPUMS International /
# Statistics South Africa). The 2011 census agrees on the 15-59 summary
# (45q15 tilt -0.80 in all three censuses) but links only 9% of deaths and
# has no band-level rows outside 30-44.
ADULT_MORT_TILTS = {
    (15, 29): (-0.9155 - 1.2085) / 2,
    (30, 44): (-1.1703 - 1.2545) / 2,
    (45, 59): (-0.8629 - 1.2122) / 2,
    (60, 74): (-0.3201 - 0.5650) / 2,
}
# Ages 1-14 have no adult-style measure; the DHS 2016 under-five tilt is the
# closest measured child gradient.
CHILD_MORT_TILT = -0.7036


def mortality_gradient(max_age=99):
    """
    Age profile of the mortality tilt for ages 0 to ``max_age``, in ogcore
    units (per centered percentile point).

    Age 0 takes the infant tilt, ages 1-14 the under-five tilt, ages 15-74
    the census age-band tilts. Above 74 there is no measurement; the gradient
    fades with age in every census measured, so it declines linearly from
    the 60-74 value to zero at ``max_age``.
    """
    ages = np.arange(max_age + 1)
    tilt = np.zeros(max_age + 1)
    tilt[0] = INFMORT_TILT
    tilt[1:15] = CHILD_MORT_TILT
    for (lo, hi), value in ADULT_MORT_TILTS.items():
        tilt[lo : hi + 1] = value
    old = ages > 74
    tilt[old] = (
        ADULT_MORT_TILTS[(60, 74)] * (max_age - ages[old]) / (max_age - 74)
    )
    return tilt / 100


def get_demographics_and_e(p, demographic_data_path=None, output_path=None):
    """
    Download the demographic objects and build the earnings matrix from
    them, so the two always come from the same population weights.

    Args:
        p (OG-Core Specifications object): model parameters
        demographic_data_path (str): path to save demographic data
        output_path (str): path to save the earnings-profile plots to

    Returns:
        tuple: (dict of demographic parameters, ``e`` array)
    """
    from ogcore import demographics

    window = dict(
        country_id=UN_COUNTRY_CODE,
        initial_data_year=p.start_year - 1,
        final_data_year=DEMOG_FINAL_DATA_YEAR,
        income_percentiles=p.lambdas.flatten(),
        fert_gradient=FERT_TILT / 100,
        mort_gradient=mortality_gradient(),
        infmort_gradient=INFMORT_TILT / 100,
        GraphDiag=False,
    )
    demog = demographics.get_pop_objs(
        p.E,
        p.S,
        p.T,
        0,
        99,
        download_path=demographic_data_path,
        **window,
    )
    # demographics for 80 period lives (needed for getting e below)
    demog80 = demographics.get_pop_objs(20, 80, p.T, 0, 99, **window)
    e = income.get_e_interp(
        p.E,
        p.S,
        demog["omega_SS"],
        demog80["omega_SS"],
        p.lambdas,
        plot_path=output_path,
    )
    return demog, e


[docs] class Calibration: """OG-ZAF calibration class""" def __init__( self, p, macro_data_start_year=datetime.datetime(1947, 1, 1), macro_data_end_year=datetime.datetime(2024, 12, 31), demographic_data_path=None, output_path=None, # Set True to update from World Bank and UN APIs update_from_api=False, ): """ Constructor for the Calibration class. Args: p (OG-Core Specifications object): model parameters demographic_data_path (str): path to save demographic data output_path (str): path to save output to update_from_api (bool): Set True if you want to pull updated macro data from World Bank and UN APIs Returns: None """ # Create output_path if it doesn't exist if output_path is not None: if not os.path.exists(output_path): os.makedirs(output_path) # Initialize attributes — populated only when update succeeds self.macro_params = {} self.demographic_params = {} self.e = None self.alpha_c = np.array([1.0]) if p.I == 1 else None self.io_matrix = np.array([[1.0]]) if p.M == 1 else None if not update_from_api: return # --- Online path: try each source independently --- # Macro estimation try: self.macro_params = macro_params.get_macro_params( macro_data_start_year, macro_data_end_year, update_from_api=update_from_api, ) except Exception as exc: warnings.warn(f"Macro params update failed: {exc}", stacklevel=2) # io matrix and alpha_c (multi-sector only) if p.I > 1: try: alpha_c_dict = io.get_alpha_c() assert p.I == len(list(alpha_c_dict.keys())) self.alpha_c = np.array(list(alpha_c_dict.values())) except Exception as exc: warnings.warn(f"alpha_c update failed: {exc}", stacklevel=2) if p.M > 1: try: io_df = io.get_io_matrix() assert p.M == len(list(io_df.keys())) self.io_matrix = io_df.values except Exception as exc: warnings.warn(f"io_matrix update failed: {exc}", stacklevel=2) # Demographics + income (atomic — e depends on demographic output) try: self.demographic_params, self.e = get_demographics_and_e( p, demographic_data_path, output_path ) except Exception as exc: warnings.warn( f"Demographics/income update failed: {exc}", stacklevel=2 ) self.demographic_params = {} self.e = None # method to return all newly calibrated parameters in a dictionary def get_dict(self): d = {} d.update(self.macro_params) d.update(self.demographic_params) if self.e is not None: d["e"] = self.e if self.alpha_c is not None: d["alpha_c"] = self.alpha_c if self.io_matrix is not None: d["io_matrix"] = self.io_matrix return d