Demographics Functions

Demographics Functions#

demographics.py modules

ogcore.demographics#

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

ogcore.demographics.expand_pop_obj_J(omega_path_lev, omega_path_S, omega_SSfx, fert_rates, mort_rates, infmort_rates, imm_rates, mort_rates_S, imm_rates_mat, E, S, g_n_SS, fixper, income_percentiles=None, fert_gradient=None, mort_gradient=None, infmort_gradient=None, imm_pctiles=None)[source]#

Expand aggregate demographic objects to age x income-group objects.

The aggregate population path and rates are left unchanged. If income_percentiles is None and no income-specific inputs are provided, the aggregate objects are broadcast across a single income group (J=1). Otherwise, income_percentiles gives the initial population distribution across J for every age and the income shares of newborns in every period.

Parameters:

  • omega_path_lev (Numpy array) – T+S x E+S aggregate population levels.

  • omega_path_S (Numpy array) – T+S x S aggregate active-age population shares.

  • omega_SSfx (Numpy array) – fixed full-life population distribution.

  • fert_rates (Numpy array) – T+S x E+S fertility rates.

  • mort_rates (Numpy array) – T+S x E+S mortality rates.

  • infmort_rates (Numpy array) – T+S infant mortality rates.

  • imm_rates (Numpy array) – T+S x E+S immigration rates, including the adjusted post-fixper rates.

  • mort_rates_S (Numpy array) – T+S x S mortality rates for active ages.

  • imm_rates_mat (Numpy array) – T+S x S immigration rates for active ages.

  • E (int) – number of non-economically active periods.

  • S (int) – number of economically active periods.

  • g_n_SS (float) – steady-state population growth rate.

  • fixper (int) – period at which the fixed steady-state distribution is imposed.

  • income_percentiles (array_like) – population shares for each J group; defaults to a single income group when no income-specific inputs are supplied.

  • fert_gradient (array_like) – log-odds fertility slopes by age.

  • mort_gradient (array_like) – log-odds mortality slopes by age.

  • infmort_gradient (array_like) – log-odds infant mortality slopes.

  • imm_pctiles (array_like) – immigrant income shares by period,

  • age

  • J. (and)

Returns:

demographic objects with the same keys needed by get_pop_objs.

Return type:

dict

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, 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)

  • 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

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, fert_gradient=None, mort_gradient=None, infmort_gradient=None, imm_pctiles=None, income_percentiles=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

  • fert_gradient (array_like) – user provided fertility rate gradient, dimensions are S, represents the log-odds slope in the fertility rate per percentile of the lifetime income distribution.

  • mort_gradient (array_like) – user provided mortality rate gradient, dimensions are S, represents the log-odds slope in the mortality rate per percentile of the lifetime income distribution.

  • infmort_gradient (array_like) – user provided infant mortality rate gradient, dimensions are S, represents the log-odds slope in the infant mortality rate per percentile of the lifetime income distribution.

  • imm_pctiles (array_like) – user provided lifetime income distribution for new immigrants, shape is num_per x S x J, where num_per is the number of years between initial and final_data_year

  • income_percentiles (array_like) – user provided income percentiles, dimensions are J, the number of lifetime income groups; defaults to a single income group (J=1) when no income-specific inputs are supplied

  • 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, un_token=None)[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

  • un_token (str) – UN Data Portal API token, resolved from the environment or the user’s token file when not given

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.og_token_command()[source]#

This function returns the full path of the og-token command that belongs to the running interpreter, so that a message can tell the user exactly what to type. The command is installed beside the interpreter and is usually not on the shell’s PATH, because OG-Core is normally run from a project virtual environment.

Returns:

full path to og-token, or None when it is not

installed alongside this interpreter

Return type:

command (str)

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)

ogcore.demographics.resolve_un_token(un_token=None)[source]#

This function finds the UN Data Portal API token to use for a request. Sources are tried in order and the first one that is present wins:

  1. the un_token argument

  2. the UN_API_TOKEN environment variable

  3. the per-user file at un_token_path()

  4. un_api_token.txt in the current working directory (deprecated)

When no source holds a token the user is asked for one and the answer is saved to the per-user file, so a token is entered once per machine rather than once per directory. The prompt is skipped when standard input is not interactive, in which case an empty token is returned and the caller falls back to the Population-Data archive.

Parameters:

un_token (str) – token supplied by the caller, overrides all other sources

Returns:

normalized token, empty string if none was found

Return type:

un_token (str)

ogcore.demographics.un_token_expiry(un_token)[source]#

This function reads the expiry date out of a UN Data Portal API token. The portal issues JSON Web Tokens, whose middle segment carries an exp claim, so the date can be read without a network call. The signature is not checked and is not needed here: the portal remains the authority on whether a token is accepted, and this is only used to tell a user that renewing is due.

Parameters:

un_token (str) – token to inspect

Returns:

expiry date, or None when the token is not

a readable JSON Web Token

Return type:

expiry (datetime.date)

ogcore.demographics.un_token_path()[source]#

This function returns the path of the per-user file that holds the UN Data Portal API token. The location follows the platform convention for user configuration files: $XDG_CONFIG_HOME (or ~/.config when that is unset) on macOS and Linux, and %APPDATA% on Windows.

Returns:

full path to the user’s UN API token file

Return type:

path (str)