Demographics Functions

Demographics Functions#

demographics.py modules

ogcore.demographics#

abbreviations is available at https://unstats.un.org/unsd/methodology/m49/#

ogcore.demographics.get_fert(totpers=100, min_age=0, max_age=99, country_id='840', start_year=2024, end_year=2024, graph=False, plot_path=None, download_path=None)[source]#

This function generates a vector of fertility rates by model period age that corresponds to the fertility rate data by age in years.

Parameters:

  • totpers (int) – total number of agent life periods (E+S), >= 3

  • min_age (int) – age in years at which agents are born, >= 0

  • max_age (int) – age in years at which agents die with certainty, >= 4, < 100 (max age in UN data is 99, 100+ i same group)

  • country_id (str) – country id for UN data

  • start_year (int) – start year for UN data

  • end_year (int) – end year for UN data

  • graph (bool) – =True if want graphical output

  • plot_path (str) – path to save fertility rate plot

  • download_path (str) – path to save fertility rate data

Returns:

fertility rates for each year of data

and model age

fig (Matplotlib Figure): figure object if graph=True and plot_path=None

Return type:

fert_rates (Numpy array)

ogcore.demographics.get_imm_rates(totpers=100, min_age=0, max_age=99, fert_rates=None, mort_rates=None, infmort_rates=None, pop_dist=None, country_id='840', start_year=2024, end_year=2024, graph=False, plot_path=None, download_path=None)[source]#

Calculate immigration rates by age as a residual given population levels in different periods, then output average calculated immigration rate. We have to replace the first mortality rate in this function in order to adjust the first implied immigration rate

Parameters:

  • totpers (int) – total number of agent life periods (E+S), >= 3

  • min_age (int) – age in years at which agents are born, >= 0

  • max_age (int) – age in years at which agents die with certainty, >= 4

  • fert_rates (Numpy array) – fertility rates for each year of data and model age

  • mort_rates (Numpy array) – mortality rates for each year of data and model age

  • infmort_rates (Numpy array) – infant mortality rates for each year of data

  • pop_dist (Numpy array) – population distribution over T0+1 periods

  • country_id (str) – country id for UN data

  • start_year (int) – start year for UN data

  • end_year (int) – end year for UN data

  • graph (bool) – =True if want graphical output

  • plot_path (str) – path to save figure to

  • download_path (str) – path to save immigration rate data

Returns:

immigration rates that correspond to

each year of data and period of life, length E+S

Return type:

imm_rates_2D (Numpy array)

ogcore.demographics.get_mort(totpers=100, min_age=0, max_age=99, country_id='840', start_year=2024, end_year=2024, graph=False, plot_path=None, download_path=None)[source]#

This function generates a vector of mortality rates by model period age.

Parameters:

  • totpers (int) – total number of agent life periods (E+S), >= 3

  • min_age (int) – age in years at which agents are born, >= 0

  • max_age (int) – age in years at which agents die with certainty, >= 4, < 100 (max age in UN data is 99, 100+ i same group)

  • country_id (str) – country id for UN data

  • start_year (int) – start year for UN data

  • end_year (int) – end year for UN data

  • graph (bool) – =True if want graphical output

  • plot_path (str) – path to save mortality rate plot

  • download_path (str) – path to save mortality rate data

Returns:

mort_rates (Numpy array) mortality rates for each year of data

and model age

infmort_rate_vec (Numpy array): infant mortality rates for each fig (Matplotlib Figure): figure object if graph=True and plot_path=None

ogcore.demographics.get_pop(E=20, S=80, min_age=0, max_age=99, infer_pop=False, fert_rates=None, mort_rates=None, infmort_rates=None, imm_rates=None, initial_pop=None, pre_pop_dist=None, country_id='840', start_year=2024, end_year=2024, download_path=None)[source]#

Retrieves the population distribution data from the UN data API

Parameters:

  • E (int) – number of model periods in which agent is not economically active, >= 1

  • S (int) – number of model periods in which agent is economically active, >= 3

  • min_age (int) – age in years at which agents are born, >= 0

  • max_age (int) – age in years at which agents die with certainty, >= 4, < 100 (max age in UN data is 99, 100+ i same group)

  • infer_pop (bool) – =True if want to infer the population from the given fertility, mortality, and immigration rates

  • fert_rates (Numpy array) – fertility rates for each year of data and model age

  • mort_rates (Numpy array) – mortality rates for each year of data and model age

  • infmort_rates (Numpy array) – infant mortality rates for each year of data

  • imm_rates (Numpy array) – immigration rates for reach year of data and model age

  • initial_pop_data (Pandas DataFrame) – initial population data for the first year of model calibration (start_year)

  • pre_pop_dist (Numpy array) – population distribution for the year before the initial year for calibration

  • country_id (str) – country id for UN data

  • start_year (int) – start year data

  • end_year (int) – end year for data

  • download_path (str) – path to save population distribution data

Returns:

population distribution over T0 periods pre_pop (Numpy array): population distribution one year before

initial year for calibration of omega_S_preTP

Return type:

pop_2D (Numpy array)

ogcore.demographics.get_pop_objs(E=20, S=80, T=320, min_age=0, max_age=99, fert_rates=None, mort_rates=None, infmort_rates=None, imm_rates=None, infer_pop=False, pop_dist=None, pre_pop_dist=None, country_id='840', initial_data_year=2023, final_data_year=2026, GraphDiag=True, download_path=None)[source]#

This function produces the demographics objects to be used in the OG-USA model package.

Parameters:

  • E (int) – number of model periods in which agent is not economically active, >= 1

  • S (int) – number of model periods in which agent is economically active, >= 3

  • T (int) – number of periods to be simulated in TPI, > 2*S

  • min_age (int) – age in years at which agents are born, >= 0

  • max_age (int) – age in years at which agents die with certainty, >= 4, < 100 (max age in UN data is 99, 100+ i same group)

  • fert_rates (array_like) – user provided fertility rates, dimensions are T0 x E+S

  • mort_rates (array_like) – user provided mortality rates, dimensions are T0 x E+S

  • infmort_rates (array_like) – user provided infant mortality rates, length T0

  • imm_rates (array_like) – user provided immigration rates, dimensions are T0 x E+S

  • infer_pop (bool) – =True if want to infer the population

  • pop_dist (array_like) – user provided population distribution, dimensions are T0+1 x E+S

  • pre_pop_dist (array_like) – user provided population distribution for the year before the initial year for calibration, length E+S

  • country_id (str) – country id for UN data

  • initial_data_year (int) – initial year of data to use (not relevant if have user provided data)

  • final_data_year (int) – final year of data to use, T0=initial_year-final_year + 1

  • pop_dist – user provided population distribution, last dimension is of length E+S

  • GraphDiag (bool) – =True if want graphical output and printed diagnostics

Returns:

includes:
omega_path_S (Numpy array), time path of the population

distribution from the current state to the steady-state, size T+S x S

g_n_SS (scalar): steady-state population growth rate omega_SS (Numpy array): normalized steady-state population

distribution, length S

surv_rates (Numpy array): survival rates that correspond to

each model period of life, length S

mort_rates (Numpy array): mortality rates that correspond to

each model period of life, length S

g_n_path (Numpy array): population growth rates over the time

path, length T + S

Return type:

pop_dict (dict)

ogcore.demographics.get_un_data(variable_code, country_id='840', start_year=2024, end_year=2024)[source]#

This function retrieves data from the United Nations Data Portal API for UN population data (see https://population.un.org/dataportal/about/dataapi)

Parameters:

  • variable_code (str) – variable code for UN data

  • country_id (str) – country id for UN data

  • start_year (int) – start year for UN data

  • end_year (int) – end year for UN data

Returns:

DataFrame of UN data

Return type:

df (Pandas DataFrame)

ogcore.demographics.immsolve(imm_rates, *args)[source]#

This function generates a vector of errors representing the difference in two consecutive periods stationary population distributions. This vector of differences is the zero-function objective used to solve for the immigration rates vector, similar to the original immigration rates vector from get_imm_rates(), that sets the steady-state population distribution by age equal to the population distribution in period int(1.5*S)

Parameters:

  • imm_rates (Numpy array) – immigration rates that correspond to each period of life, length E+S

  • args (tuple) – (fert_rates, mort_rates, infmort_rates, omega_cur, g_n_SS)

Returns:

difference between omega_new and

omega_cur_pct, length E+S

Return type:

omega_errs (Numpy array)

ogcore.demographics.pop_rebin(curr_pop_dist, totpers_new)[source]#

For cases in which totpers (E+S) is less than the number of periods in the population distribution data, this function calculates a new population distribution vector with totpers (E+S) elements.

Parameters:

  • curr_pop_dist (Numpy array) – population distribution over N periods

  • totpers_new (int) – number of periods to which we are transforming the population distribution, >= 3

Returns:

new population distribution over

totpers (E+S) periods that approximates curr_pop_dist

Return type:

curr_pop_new (Numpy array)