Calibration#

This file has various classes and functions for constructing income processes.

class HARK.Calibration.Income.IncomeProcesses.BinaryIncShkDstn(shk_prob, shk_val, seed=0)#

Bases: DiscreteDistribution

A one period income shock distribution (transitory, permanent, or other) with only two outcomes. One probability and value are specified, and the other is implied to make it a mean one distribution.

Parameters:

  • shk_prob (float) – Probability of one of the income shock outcomes.

  • shk_val (float) – Value of the specified income shock outcome.

  • seed (int, optional) – Random seed. The default is 0.

Returns:

ShkDstn – Binary income shock distribuion.

Return type:

DiscreteDistribution

class HARK.Calibration.Income.IncomeProcesses.LognormPermIncShk(sigma, n_approx, neutral_measure=False, seed=0)#

Bases: DiscreteDistribution

A one-period distribution of a multiplicative lognormal permanent income shock. :param sigma: Standard deviation of the log-shock. :type sigma: float :param n_approx: Number of points to use in the discrete approximation. :type n_approx: int :param neutral_measure: Whether to use Harmenberg’s permanent-income-neutral measure. The default is False. :type neutral_measure: Bool, optional :param seed: Random seed. The default is 0. :type seed: int, optional

Returns:

PermShkDstn – Permanent income shock distribution.

Return type:

DiscreteDistribution

class HARK.Calibration.Income.IncomeProcesses.MixtureTranIncShk(sigma, UnempPrb, IncUnemp, n_approx, seed=0)#

Bases: DiscreteDistribution

A one-period distribution for transitory income shocks that are a mixture between a log-normal and a single-value unemployment shock.

Parameters:

  • sigma (float) – Standard deviation of the log-shock.

  • UnempPrb (float) – Probability of the “unemployment” shock.

  • IncUnemp (float) – Income shock in the “unemployment” state.

  • n_approx (int) – Number of points to use in the discrete approximation.

  • seed (int, optional) – Random seed. The default is 0.

Returns:

TranShkDstn – Transitory income shock distribution.

Return type:

DiscreteDistribution

class HARK.Calibration.Income.IncomeProcesses.MixtureTranIncShk_HANK(sigma, UnempPrb, IncUnemp, n_approx, wage, labor, tax_rate, seed=0)#

Bases: DiscreteDistribution

A one-period distribution for transitory income shocks that are a mixture between a log-normal and a single-value unemployment shock. This version has additional parameters that makes it useful for HANK models.

Parameters:

  • sigma (float) – Standard deviation of the log-shock.

  • UnempPrb (float) – Probability of the “unemployment” shock.

  • IncUnemp (float) – Income shock in the “unemployment” state.

  • n_approx (int) – Number of points to use in the discrete approximation.

  • tax_rate (float) – Flat tax rate on labor income.

  • labor (float) – Intensive margin labor supply.

  • wage (float) – Wage rate scaling factor.

  • seed (int, optional) – Random seed. The default is 0.

Returns:

TranShkDstn – Transitory income shock distribution.

Return type:

DiscreteDistribution

class HARK.Calibration.Income.IncomeProcesses.BufferStockIncShkDstn(sigma_Perm, sigma_Tran, n_approx_Perm, n_approx_Tran, UnempPrb, IncUnemp, neutral_measure=False, seed=0)#

Bases: DiscreteDistributionLabeled

A one-period distribution object for the joint distribution of income shocks (permanent and transitory), as modeled in the Buffer Stock Theory paper: - Lognormal, discretized permanent income shocks. - Transitory shocks that are a mixture of: - A lognormal distribution in normal times. - An “unemployment” shock.

Parameters:

  • sigma_Perm (float) – Standard deviation of the log- permanent shock.

  • sigma_Tran (float) – Standard deviation of the log- transitory shock.

  • n_approx_Perm (int) – Number of points to use in the discrete approximation of the permanent shock.

  • n_approx_Tran (int) – Number of points to use in the discrete approximation of the transitory shock.

  • UnempPrb (float) – Probability of the “unemployment” shock.

  • IncUnemp (float) – Income shock in the “unemployment” state.

  • neutral_measure (Bool, optional) – Whether to use Hamenberg’s permanent-income-neutral measure. The default is False.

  • seed (int, optional) – Random seed. The default is 0.

Returns:

IncShkDstn – Income shock distribution.

Return type:

DiscreteDistribution

class HARK.Calibration.Income.IncomeProcesses.IncShkDstn_HANK(sigma_Perm, sigma_Tran, n_approx_Perm, n_approx_Tran, UnempPrb, IncUnemp, tax_rate, labor, wage, neutral_measure=False, seed=0)#

Bases: DiscreteDistributionLabeled

A one-period distribution object for the joint distribution of income shocks (permanent and transitory), as modeled in the Buffer Stock Theory paper: - Lognormal, discretized permanent income shocks. - Transitory shocks that are a mixture of: - A lognormal distribution in normal times. - An “unemployment” shock.

This version has additional features that make it particularly useful for HANK models.

Parameters:

  • sigma_Perm (float) – Standard deviation of the log- permanent shock.

  • sigma_Tran (float) – Standard deviation of the log- transitory shock.

  • n_approx_Perm (int) – Number of points to use in the discrete approximation of the permanent shock.

  • n_approx_Tran (int) – Number of points to use in the discrete approximation of the transitory shock.

  • UnempPrb (float) – Probability of the “unemployment” shock.

  • IncUnemp (float) – Income shock in the “unemployment” state.

  • tax_rate (float) – Flat tax rate on labor income.

  • labor (float) – Intensive margin labor supply.

  • wage (float) – Wage rate scaling factor.

  • neutral_measure (Bool, optional) – Whether to use Harmenberg’s permanent-income-neutral measure. The default is False.

  • seed (int, optional) – Random seed. The default is 0.

Returns:

IncShkDstn – Income shock distribution.

Return type:

DiscreteDistribution

HARK.Calibration.Income.IncomeProcesses.construct_lognormal_income_process_unemployment(T_cycle, PermShkStd, PermShkCount, TranShkStd, TranShkCount, T_retire, UnempPrb, IncUnemp, UnempPrbRet, IncUnempRet, RNG, neutral_measure=False)#

Generates a list of discrete approximations to the income process for each life period, from end of life to beginning of life. Permanent shocks (\(\psi\)) are mean one lognormally distributed with standard deviation PermShkStd[t] during the working life, and degenerate at 1 in the retirement period. Transitory shocks (\(\theta\)) are mean one lognormally distributed with a point mass at IncUnemp with probability UnempPrb while working; they are mean one with a point mass at IncUnempRet with probability UnempPrbRet. Retirement occurs after t=T_retire periods of working.

\[\begin{split}\begin{align*} \psi_t &\sim \begin{cases} \exp(\mathcal{N}(-\textbf{PermShkStd}_{t}^{2}/2,\textbf{PermShkStd}_{t}^{2})) & \text{if } t \leq t_{\text{retire}}\\ 1 & \text{if } t > t_{\text{retire}} \end{cases}\\ p_{\text{unemp}} & = \begin{cases} \textbf{UnempPrb} & \text{if } t \leq t_{\text{retire}} \\ \textbf{UnempPrbRet} & \text{if } t > t_{\text{retire}} \\ \end{cases}\\ &\text{if } p > p_{\text{unemp}} \\ \theta_t &\sim\begin{cases} \exp(\mathcal{N}(-\textbf{PermShkStd}_{t}^{2}/2-\ln(\frac{1-\textbf{IncUnemp }\textbf{UnempPrb}}{1-\textbf{UnempPrb}}),\textbf{PermShkStd}_{t}^{2})) & \text{if } t\leq t_{\text{retire}}\\ \frac{1-\textbf{UnempPrbRet }\textbf{IncUnempRet}}{1-\textbf{UnempPrbRet}} & \text{if } t > t_{\text{retire}} \\ \end{cases}\\ &\text{otherwise}\\ \theta_t &\sim\begin{cases} \textbf{IncUnemp} & \text{if } t\leq t_{\text{retire}}\\ \textbf{IncUnempRet} & \text{if } t\leq t_{\text{retire}}\\ \end{cases}\\ \mathbb{E}[\psi]&=\mathbb{E}[\theta] = 1.\\ \end{align*}\end{split}\]

All time in this function runs forward, from t=0 to t=T

Parameters:

  • PermShkStd ([float]) – List of standard deviations in log permanent income uncertainty during the agent’s life.

  • PermShkCount (int) – The number of approximation points to be used in the discrete approximation to the permanent income shock distribution.

  • TranShkStd ([float]) – List of standard deviations in log transitory income uncertainty during the agent’s life.

  • TranShkCount (int) – The number of approximation points to be used in the discrete approximation to the permanent income shock distribution.

  • UnempPrb (float or [float]) – The probability of becoming unemployed during the working period.

  • UnempPrbRet (float or None) – The probability of not receiving typical retirement income when retired.

  • T_retire (int) – The index value for the final working period in the agent’s life. If T_retire <= 0 then there is no retirement.

  • IncUnemp (float or [float]) – Transitory income received when unemployed.

  • IncUnempRet (float or None) – Transitory income received while “unemployed” when retired.

  • T_cycle (int) – Total number of non-terminal periods in the consumer’s sequence of periods.

  • RNG (np.random.RandomState) – Random number generator for this type.

  • neutral_measure (bool) – Indicator for whether the permanent-income-neutral measure should be used.

Returns:

IncShkDstn – A list with T_cycle elements, each of which is a discrete approximation to the income process in a period.

Return type:

[distribution.Distribution]

HARK.Calibration.Income.IncomeProcesses.construct_HANK_lognormal_income_process_unemployment(T_cycle, PermShkStd, PermShkCount, TranShkStd, TranShkCount, T_retire, UnempPrb, IncUnemp, UnempPrbRet, IncUnempRet, tax_rate, labor, wage, RNG, neutral_measure=False)#

Generates a list of discrete approximations to the income process for each life period, from end of life to beginning of life. Permanent shocks are mean one lognormally distributed with standard deviation PermShkStd[t] during the working life, and degenerate at 1 in the retirement period. Transitory shocks are mean one lognormally distributed with a point mass at IncUnemp with probability UnempPrb while working; they are mean one with a point mass at IncUnempRet with probability UnempPrbRet. Retirement occurs after t=T_retire periods of working.

This version of the function incorporates additional flexibility with respect to transitory income (continuous labor supply, wage rate, tax rate) and thus is useful in HANK models (hence the name!).

Note 1: All time in this function runs forward, from t=0 to t=T

Note 2: All parameters are passed as attributes of the input parameters.

Parameters (passed as attributes of the input parameters)#

PermShkStd[float]

List of standard deviations in log permanent income uncertainty during the agent’s life.

PermShkCountint

The number of approximation points to be used in the discrete approxima- tion to the permanent income shock distribution.

TranShkStd[float]

List of standard deviations in log transitory income uncertainty during the agent’s life.

TranShkCountint

The number of approximation points to be used in the discrete approxima- tion to the permanent income shock distribution.

UnempPrbfloat or [float]

The probability of becoming unemployed during the working period.

UnempPrbRetfloat or None

The probability of not receiving typical retirement income when retired.

T_retireint

The index value for the final working period in the agent’s life. If T_retire <= 0 then there is no retirement.

IncUnempfloat or [float]

Transitory income received when unemployed.

IncUnempRetfloat or None

Transitory income received while “unemployed” when retired.

tax_rate[float]

List of flat tax rates on labor income, age-varying.

labor[float]

List of intensive margin labor supply, age-varying.

wage[float]

List of wage rate scaling factors, age-varying.

T_cycleint

Total number of non-terminal periods in the consumer’s sequence of periods.

returns:

  • IncShkDstn ([distribution.Distribution]) – A list with T_cycle elements, each of which is a discrete approximation to the income process in a period.

  • PermShkDstn ([[distribution.Distributiony]]) – A list with T_cycle elements, each of which a discrete approximation to the permanent income shocks.

  • TranShkDstn ([[distribution.Distribution]]) – A list with T_cycle elements, each of which a discrete approximation to the transitory income shocks.

HARK.Calibration.Income.IncomeProcesses.get_PermShkDstn_from_IncShkDstn(IncShkDstn, RNG)#
HARK.Calibration.Income.IncomeProcesses.get_TranShkDstn_from_IncShkDstn(IncShkDstn, RNG)#
HARK.Calibration.Income.IncomeProcesses.get_TranShkGrid_from_TranShkDstn(T_cycle, TranShkDstn)#
HARK.Calibration.Income.IncomeProcesses.make_polynomial_PermGroFac(T_cycle, PermGroFac_coeffs, age_0=0.0, age_step=1.0)#

Construct the profile of permanent growth factors by age using polynomial coefficients.

Parameters:

  • T_cycle (int) – Number of non-terminal period’s in this agent’s cycle.

  • PermGroFac_coeffs ([float]) – Arbitrary length list or 1D vector of polynomial coefficients of age on permanent income growth factor.

  • age_0 (float, optional) – Initial age of agents (when t_age=0), with respect to the polynomial coefficients. The default is 0.

  • age_step (float, optional) – Age increment in the model, with respect to the polynomial coefficients. The default is 1.

Returns:

PermGroFac – List of permanent income growth factors, one per period.

Return type:

[float]

HARK.Calibration.Income.IncomeProcesses.make_polynomial_PermShkStd(T_cycle, PermShkStd_coeffs, age_0=0.0, age_step=1.0)#

Construct the profile of (log) permanent income shock standard deviations by age using polynomial coefficients.

Parameters:

  • T_cycle (int) – Number of non-terminal period’s in this agent’s cycle.

  • PermGroFac_coeffs ([float]) – Arbitrary length list or 1D vector of polynomial coefficients of age on (log) permanent income shock standard deviation.

  • age_0 (float, optional) – Initial age of agents (when t_age=0), with respect to the polynomial coefficients. The default is 0.

  • age_step (float, optional) – Age increment in the model, with respect to the polynomial coefficients. The default is 1.

Returns:

PermShkStd – List of (log) permanent income shock standard deviations, one per period.

Return type:

[float]

HARK.Calibration.Income.IncomeProcesses.make_polynomial_TranShkStd(T_cycle, TranShkStd_coeffs, age_0=0.0, age_step=1.0)#

Construct the profile of (log) transitory income shock standard deviations by age using polynomial coefficients.

Parameters:

  • T_cycle (int) – Number of non-terminal period’s in this agent’s cycle.

  • PermGroFac_coeffs ([float]) – Arbitrary length list or 1D vector of polynomial coefficients of age on (log) transitory income shock standard deviation.

  • age_0 (float, optional) – Initial age of agents (when t_age=0), with respect to the polynomial coefficients. The default is 0.

  • age_step (float, optional) – Age increment in the model, with respect to the polynomial coefficients. The default is 1.

Returns:

TranShkStd – List of (log) permanent income shock standard deviations, one per period.

Return type:

[float]

class HARK.Calibration.Income.IncomeProcesses.pLvlFuncAR1(pLogMean, PermGroFac, Corr)#

Bases: MetricObject

A class for representing AR1-style persistent income growth functions.

Parameters:

  • pLogMean (float) – Log persistent income level toward which we are drawn.

  • PermGroFac (float) – Autonomous (e.g. life cycle) pLvl growth (does not AR1 decay).

  • Corr (float) – Correlation coefficient on log income.

HARK.Calibration.Income.IncomeProcesses.make_PermGroFac_from_ind_and_agg(PermGroFacInd, PermGroFacAgg)#

A very simple function that constructs overall permanent income growth over the lifecycle as the sum of idiosyncratic productivity growth PermGroFacInd and aggregate productivity growth PermGroFacAgg. In most HARK models, PermGroFac is treated as the overall permanent income growth factor, regardless of source. In applications in which the user has estimated permanent income growth from cross sectional data, or wants to investigate how a change in aggregate productivity growth affects behavior or outcomes, this function can be used as the constructor for PermGroFac.

To use this function, specify idiosyncratic productivity growth in the attribute PermGroFacInd (or construct it), and put this function as the entry for PermGroFac in the constructors dictionary of your AgentType subclass instances.

Parameters:

  • PermGroFacInd ([float] or np.array) – Lifecycle sequence of idiosyncratic permanent productivity growth factors. These represent individual-based productivity factors, like experience.

  • PermGroFacAgg (float) – Constant aggregate permanent growth factor, representing (e.g.) TFP.

Returns:

PermGroFac – Lifecycle sequence of overall permanent productivity growth factors. Returns same type as PermGroFacInd.

Return type:

[float] or np.array

HARK.Calibration.Income.IncomeProcesses.make_trivial_pLvlNextFunc(T_cycle)#

A dummy function that creates default trivial permanent income dynamics: none at all! Simply returns a list of IdentityFunctions, one for each period.

\[G_{t}(x) = x\]
Parameters:

T_cycle (int) – Number of non-terminal periods in the agent’s problem.

Returns:

pLvlNextFunc – List of trivial permanent income dynamic functions.

Return type:

[IdentityFunction]

HARK.Calibration.Income.IncomeProcesses.make_explicit_perminc_pLvlNextFunc(T_cycle, PermGroFac)#

A function that creates permanent income dynamics as a sequence of linear functions, indicating constant expected permanent income growth across permanent income levels.

\[G_{t+1} (x) = \Gamma_{t+1} x\]
Parameters:

  • T_cycle (int) – Number of non-terminal periods in the agent’s problem.

  • PermGroFac ([float]) – List of permanent income growth factors over the agent’s problem.

Returns:

pLvlNextFunc – List of linear functions representing constant permanent income growth rate, regardless of current permanent income level.

Return type:

[LinearInterp]

HARK.Calibration.Income.IncomeProcesses.make_AR1_style_pLvlNextFunc(T_cycle, pLvlInitMean, PermGroFac, PrstIncCorr)#

A function that creates permanent income dynamics as a sequence of AR1-style functions. If cycles=0, the product of PermGroFac across all periods must be 1.0, otherwise this method is invalid.

\[\begin{split}\begin{align} log(G_{t+1} (x)) &=\varphi log(x) + (1-\varphi) log(\overline{P}_{t})+log(\Gamma_{t+1}) + log(\psi_{t+1}), \\ \overline{P}_{t+1} &= \overline{P}_{t} \Gamma_{t+1} \\ \end{align}\end{split}\]
Parameters:

  • T_cycle (int) – Number of non-terminal periods in the agent’s problem.

  • pLvlInitMean (float) – Mean of log permanent income at initialization.

  • PermGroFac ([float]) – List of permanent income growth factors over the agent’s problem.

  • PrstIncCorr (float) – Correlation coefficient on log permanent income today on log permanent income in the succeeding period.

Returns:

pLvlNextFunc – List of AR1-style persistent income dynamics functions

Return type:

[pLvlFuncAR1]

HARK.Calibration.Income.IncomeProcesses.make_basic_pLvlPctiles(pLvlPctiles_count, pLvlPctiles_bound=[0.001, 0.999], pLvlPctiles_tail_count=0, pLvlPctiles_tail_order=2.718281828459045)#

Make a relatively basic specification for pLvlPctiles by choosing the number of uniformly spaced nodes in the “body”, the percentile boundaries for the body, the number of nodes in each tail, and the order/factor by which the tail percentiles approach 0 and 1 respectively.

Parameters:

  • pLvlPctile_count (int) – Number of nodes in the “body” of the percentile set.

  • pLvlPctile_bound ([float,float], optional) – Percentile bounds for the “body” of the set. The default is [0.0, 1.0].

  • pLvlPctile_tail_count (int, optional) – Number of nodes in each extant tail of the set. The default is 0.

  • pLvlPctile_tail_order (float, optional) – Factor by which tail percentiles shrink toward 0 and 1. The default is np.e.

Returns:

pLvlPctiles – Array of percentiles of pLvl, usually used to construct pLvlGrid using the function below.

Return type:

np.array

HARK.Calibration.Income.IncomeProcesses.make_pLvlGrid_by_simulation(cycles, T_cycle, PermShkDstn, pLvlNextFunc, LivPrb, pLvlInitMean, pLvlInitStd, pLvlPctiles, pLvlExtra=None)#

Construct the permanent income grid for each period of the problem by simulation. If the model is infinite horizon (cycles=0), an approximation of the long run steady state distribution of permanent income is used (by simulating many periods). If the model is lifecycle (cycles=1), explicit simulation is used. In either case, the input pLvlPctiles is used to choose percentiles from the distribution.

If the problem is neither infinite horizon nor lifecycle, this method will fail. If the problem is infinite horizon, cumprod(PermGroFac) must equal one.

Parameters:

  • cycles (int) – Number of times the sequence of periods happens for the agent; must be 0 or 1.

  • T_cycle (int) – Number of non-terminal periods in the agent’s problem.

  • PermShkDstn ([distribution]) – List of permanent shock distributions in each period of the problem.

  • pLvlNextFunc ([function]) – List of permanent income dynamic functions.

  • LivPrb ([float]) – List of survival probabilities by period of the cycle. Only used in infinite horizon specifications.

  • pLvlInitMean (float) – Mean of log permanent income at initialization.

  • pLvlInitStd (float) – Standard deviaition of log permanent income at initialization.

  • pLvlPctiles ([float]) – List or array of percentiles (between 0 and 1) of permanent income to use for the pLvlGrid.

  • pLvlExtra (None or [float], optional) – Additional pLvl values to automatically include in pLvlGrid.

Returns:

pLvlGrid – List of permanent income grids for each period, constructed by simulating the permanent income process and extracting specified percentiles.

Return type:

[np.array]

This file contains tools for creating risky asset return distributions, for use as inputs to several consumption-saving model solvers.

HARK.Calibration.Assets.AssetProcesses.make_lognormal_RiskyDstn(T_cycle, RiskyAvg, RiskyStd, RiskyCount, RNG)#

Creates a discrete approximation of lognormal risky asset returns, either as a single distribution or as a lifecycle sequence.

\[\begin{split}\begin{align} \phi_t &\sim \exp(\mathcal{N}(\textbf{RiskyStd}_{t}^2)) \\ \mathbb{E}_{t} \left[ \phi_t \right] &= \textbf{RiskyAvg}_{t}\\ \end{align}\end{split}\]
Parameters:

  • T_cycle (int) – Number of non-terminal periods in this agent’s cycle.

  • RiskyAvg (float or [float]) – Mean return factor of risky asset. If a single number, it is used for all periods. If it is a list, then it represents lifecycle returns (or perceptions thereof).

  • RiskyStd (float or [float]) – Standard deviation of log returns of the risky asset. Allows the same options as RiskyAvg.

  • RiskyCount (int) – Number of equiprobable discrete nodes in the risky return distribution.

  • RNG (RandomState) – Internal random number generator for the AgentType instance, used to generate random seeds.

Returns:

RiskyDstn – Discretized approximation to lognormal asset returns.

Return type:

DiscreteDistribution or [DiscreteDistribution]

HARK.Calibration.Assets.AssetProcesses.combine_IncShkDstn_and_RiskyDstn(T_cycle, RiskyDstn, IncShkDstn)#

Combine the income shock distribution (over PermShk and TranShk) with the risky return distribution (RiskyDstn) to make a new object called ShockDstn.

Parameters:

  • T_cycle (int) – Number of non-terminal periods in this agent’s cycle.

  • RiskyDstn (DiscreteDistribution or [DiscreteDistribution]) – Discretized approximation to lognormal asset returns.

  • IncShkDstn ([Distribution]) – A discrete approximation to the income process between each period.

Returns:

ShockDstn – A combined trivariate discrete distribution of permanent shocks, transitory shocks, and risky returns. Has one element per period of the agent’s cycle.

Return type:

IndexDistribution

HARK.Calibration.Assets.AssetProcesses.calc_ShareLimit_for_CRRA(T_cycle, RiskyDstn, CRRA, Rfree)#

Calculates the lower bound on the risky asset share as market resources go to infinity, given that utility is CRRA.

Parameters:

  • T_cycle (int) – Number of non-terminal periods in this agent’s cycle.

  • RiskyDstn (DiscreteDistribution or [DiscreteDistribution]) – Discretized approximation to lognormal asset returns.

  • CRRA (float) – Coefficient of relative risk aversion.

  • Rfree (float) – Return factor on the risk-free asset.

Returns:

ShareLimit – Lower bound on risky asset share. Can be a single number or a lifecycle sequence.

Return type:

float or [float]