Ctrl+K

Demographics Functions

Demographics Functions#

demographics.py modules

oguk.demographics#

This module contains the following functions:

get_un_fert_data() get_un_mort_data() get_wb_infmort_rate() get_un_pop_data() get_fert() get_mort() pop_rebin() get_imm_resid() immsolve() get_pop_objs() extrap_exp_3() extrap_arctan_3() ab_zero_eqs_exp_func() b_zero_eq_artctan_func()

oguk.demographics.ab_zero_eqs_exp_func(ab_vals, params)[source]#

” This function returns a vector of error values for the two zero equations in terms of parameters a and b for given values of a and b.

oguk.demographics.b_zero_eq_arctan_func(b, params)[source]#

” This function returns a scalar error value of the univariate error function in parameter b for given values of b.

oguk.demographics.extrap_arctan_3(x_vals, con_slope: float, x_con, y_con, x_eps, low: bool = True)[source]#

This function fits an arctangent function to extrapolate data that monotonically decrease to zero and start with small absolute slope, then absolute slope increases, then absolute slope decreases to zero. The arctangent function is the following with the three following identifying conditions:

if extrapolating to the low end of the data: f(x) = (a / pi) * arctan(b * x + c) + (a / 2) s.t. a, b > 0 where f’(x) = (a * b) / (pi * (1 + (b * x + c)^2))

if extrapolating to the high end of the data: f(x) = (-a / pi) * arctan(b * x + c) + (a / 2) s.t. a, b > 0 where f’(x) = (-a * b) / (pi * (1 + (b * x + c)^2))

s.t. (i) f(x_con) = y_con and (ii) f’(x_con) = con_slope and (iii) b * (2/3 * x_con + 1/3 * x_eps) + c = 0

The solution to this problem can be reduced to finding the root of a univariate equation in the parameter b.

Parameters:

  • x_vals (array_like) – array of x values to be extrapolated

  • con_slope (float) – slope of the data at the connecting value

  • x_con (float) – x value at which the function must connect to the data

  • y_con (float) – y value at which the function must connect to the data

  • x_eps (float) – x value at which the function must be close to zero

  • low (bool) – If True, the function is fit to the low end of the data. If False, the function is fit to the high end of the data.

Returns:

extrapolated y values corresponding to x values

Return type:

y_vals (array_like)

oguk.demographics.extrap_exp_3(x_vals, con_val: tuple, con_slope: float, eps_val: tuple, low: bool = True)[source]#

This function fits a smooth exponential extrapolation to either the low end of data or the high end of data, both of which are monotonically asymptoting to zero. For the exponential function extrapolation on both ends of the distribution, we use the function:

f(x) = e ** (a * (x ** 2) + b * x + c) s.t. (i) f(x_con) = y_con

  1. f’(x_con) = con_slope

  1. f’(x_eps) = eps_low (>0) or eps_high (<0)

Parameters:

  • x_vals (array_like) – array of x values to be extrapolated

  • con_val (tuple) – (x, y) coordinate at which the function must connect to the data

  • con_slope (float) – slope of the data at the connecting value

  • eps_val (tuple) – (x, y) coordinate at which the function must be close to zero

  • low (bool) – If True, the function is fit to the low end of the data. If False, the function is fit to the high end of the data.

Returns:

extrapolated y values corresponding to x values

Return type:

y_vals (array_like)

oguk.demographics.get_fert(totpers, start_year=2021, end_year=None, graph=False)[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

  • start_year (int) – first year data to download

  • end_year (int or None) – end year data to download

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

Returns:

fertility rates for each model period

of life

Return type:

fert_rates (Numpy array)

oguk.demographics.get_imm_resid(totpers, start_year=2021, end_year=None, graph=False)[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. Source: UN Population Data portal.

Parameters:

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

  • start_year (int) – first year data to download

  • end_year (int or None) – end year data to download

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

Returns:

immigration rates that correspond to

each period of life, length E+S

Return type:

imm_rates (Numpy array)

oguk.demographics.get_mort(totpers, start_year=2021, end_year=None, graph=False)[source]#

This function generates a vector of mortality rates by model period age. Source: UN Population Data portal.

Parameters:

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

  • start_year (int) – first year data to download

  • end_year (int or None) – end year data to download

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

Returns:

mort_rates (Numpy array) mortality rates that correspond to each

period of life

infmort_rate (scalar): infant mortality rate

oguk.demographics.get_pop_objs(E, S, T, curr_year, GraphDiag=False)[source]#

This function produces the demographics objects to be used in the OG-ZAF 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

  • curr_year (int) – current year for which analysis will begin, >= 2016

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

oguk.demographics.get_un_fert_data(country_id: str = '826', start_year: int = 2021, end_year: int | None = None, download: bool = True) → DataFrame[source]#

Get UN fertility rate data for a country for some range of years (at least one year) and by age. The country_id=826 is for United Kingdom. These data come from the United Nations Data Portal API for UN population data (see https://population.un.org/dataportal/about/dataapi)

Parameters:

  • country_id (str) – 3-digit country id (numerical)

  • start_year (int) – beginning year of the data

  • end_year (int or None) – end year of the data

  • download (bool) – whether to download the data from the UN Data Portal. If False, a path must be specified in the path_folder argument.

  • path_folder (None or str) – string path to folder where data are stored

Returns:

dataset with fertility rates by age

Return type:

fert_rates_df (DataFrame)

oguk.demographics.get_un_mort_data(country_id: str = '826', start_year: int = 2021, end_year: int | None = None, download: bool = True) → DataFrame[source]#

Get UN mortality rate data for a country for some range of years (at least one year) and by age, and get infant mortality rate data. The country_id=826 is for United Kingdom. These data come from the United Nations Population Data Portal API for UN population data (see https://population.un.org/dataportal/about/dataapi)

Parameters:

  • country_id (str) – 3-digit country id (numerical)

  • start_year (int) – beginning year of the data

  • end_year (int or None) – end year of the data

  • download (bool) – whether to download the data from the UN Data Portal. If False, a path must be specified in the path_folder argument.

  • path_folder (None or str) – string path to folder where data are stored

Returns:

dataset with infant mortality rates by yr mort_rates_df(DataFrame): dataset with mortality rates by age

Return type:

infmort_rate_df (DataFrame)

oguk.demographics.get_un_pop_data(country_id: str = '826', start_year: int = 2021, end_year: int | None = None, download: bool = True) → DataFrame[source]#

Get UN population data for a country for some range of years (at least one year) and by age. The country_id=826 is for United Kingdom. These data come from the United Nations Data Portal API for UN population data (see https://population.un.org/dataportal/about/dataapi)

Parameters:

  • country_id (str) – 3-digit country id (numerical)

  • start_year (int) – beginning year of the data

  • end_year (int) – end year of the data

  • download (bool) – whether to download the data from the UN Data Portal. If False, a path must be specified in the path_folder argument.

  • path_folder (None or str) – string path to folder where data are stored

Returns:

dataset with total population by age

Return type:

pop_df (DataFrame)

oguk.demographics.get_wb_infmort_rate(country: str = 'GBR', start_year: int = 2020, end_year: int | None = None, download: bool = True) → float64[source]#

Get World Bank infant mortality rate measure from neonatal mortality rate (deaths per 1,000 live births, divided by 1,0000) https://data.worldbank.org/indicator/SH.DYN.NMRT

Parameters:

  • country (str) – 3-digit country id (alphabetic)

  • start_year (int) – beginning year of the data

  • end_year (int or None) – end year of the data

  • download (bool) – whether to download the data from the UN Data Portal. If False, a path must be specified in the path_folder argument.

Returns:

neonatal infant mortality rate

Return type:

wb_infmort_rate (float)

oguk.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_resid(), 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_rate, omega_cur, g_n_ss)

Returns:

difference between omega_new and

omega_cur_pct, length E+S

Return type:

omega_errs (Numpy array)

oguk.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)

Contents