Demographics Functions#
demographics.py modules
ogcore.demographics#
- 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)