Interactive online version:
.
Download notebook.
Consumption-Saving model with Idiosyncratic Income Shocks#
The ``IndShockConsumerType`` class
[1]:
# Initial imports and notebook setup, click arrow to show
import matplotlib.pyplot as plt
import numpy as np
from HARK.ConsumptionSaving.ConsIndShockModel import IndShockConsumerType
from HARK.utilities import plot_funcs, plot_funcs_der
mystr = lambda number: f"{number:.4f}"
The module HARK.ConsumptionSaving.ConsIndShockModel concerns consumption-saving models with idiosyncratic shocks to (non-capital) income. All of the models assume CRRA utility with geometric discounting, no bequest motive, and income shocks are fully transitory or fully permanent.
ConsIndShockModel includes: 1. A very basic “perfect foresight” model with no uncertainty. 2. A model with risk over transitory and permanent income shocks. 3. The model described in (2), with an interest rate for debt that differs from the interest rate for savings.
This notebook provides documentation for the second of these models. \(\newcommand{\CRRA}{\rho}\) \(\newcommand{\DiePrb}{\mathsf{D}}\) \(\newcommand{\PermGroFac}{\Gamma}\) \(\newcommand{\Rfree}{\mathsf{R}}\) \(\newcommand{\DiscFac}{\beta}\)
Statement of idiosyncratic income shocks model#
Suppose we want to solve a model like the one analyzed in BufferStockTheory, which has all the same features as the perfect foresight consumer, plus idiosyncratic shocks to income each period. Agents with this kind of model are represented by the class IndShockConsumerType.
Specifically, this type of consumer receives two income shocks at the beginning of each period: a completely transitory shock \(\newcommand{\tShkEmp}{\theta}{\tShkEmp_t}\) and a completely permanent shock \(\newcommand{\pShk}{\psi}{\pShk_t}\). Moreover, the agent is subject to borrowing a borrowing limit: the ratio of end-of-period assets \(A_t\) to permanent income \(P_t\) must be greater than \(\underline{a}\). As with the perfect foresight problem, this model is stated in terms of normalized variables, dividing all real variables by \(P_t\):
\begin{align*} v_t(m_t) &= \max_{c_t} u(c_t) + \DiscFac (1-\DiePrb_{t+1}) \mathbb{E}_{t} \left[ (\PermGroFac_{t+1}\psi_{t+1})^{1-\CRRA} v_{t+1}(m_{t+1}) \right], \\ a_t &= m_t - c_t, \\ a_t &\geq \text{$\underline{a}$}, \\ m_{t+1} &= \Rfree/(\PermGroFac_{t+1} \psi_{t+1}) a_t + \theta_{t+1}, \\ (\psi_{t+1},\theta_{t+1}) &\sim F_{t+1}, \\ \mathbb{E}[\psi]=\mathbb{E}[\theta] &= 1, \\ u(c) &= \frac{c^{1-\rho}}{1-\rho}. \end{align*}
Solution method for IndShockConsumerType#
With the introduction of (non-trivial) risk, the idiosyncratic income shocks model has no closed form solution and must be solved numerically. The function solveConsIndShock solves the one period problem for the IndShockConsumerType class. To do so, HARK uses the original version of the endogenous grid method (EGM) first described here; see also the
SolvingMicroDSOPs lecture notes.
Briefly, the transition equation for \(m_{t+1}\) can be substituted into the problem definition; the second term of the reformulated maximand represents “end of period value of assets” \(\mathfrak{v}_t(a_t)\) (“Gothic v”):
\begin{align*} v_t(m_t) &= \max_{c_t} {~} u(c_t) + \underbrace{\DiscFac (1-\DiePrb_{t+1}) \mathbb{E}_{t} \left[ (\PermGroFac_{t+1}\psi_{t+1})^{1-\CRRA} v_{t+1}(\Rfree/(\PermGroFac_{t+1} \psi_{t+1}) a_t + \theta_{t+1}) \right]}_{\equiv \mathfrak{v}_t(a_t)}. \end{align*}
The first order condition with respect to \(c_t\) is thus simply:
\begin{align*} u^{\prime}(c_t) - \mathfrak{v}'_t(a_t) = 0 \Longrightarrow c_t^{-\CRRA} = \mathfrak{v}'_t(a_t) \Longrightarrow c_t = \mathfrak{v}'_t(a_t)^{-1/\CRRA}, \end{align*}
and the marginal value of end-of-period assets can be computed as:
\begin{align*} \mathfrak{v}'_t(a_t) = \DiscFac (1-\DiePrb_{t+1}) \mathbb{E}_{t} \left[ \Rfree (\PermGroFac_{t+1}\psi_{t+1})^{-\CRRA} v'_{t+1}(\Rfree/(\PermGroFac_{t+1} \psi_{t+1}) a_t + \theta_{t+1}) \right]. \end{align*}
To solve the model, we choose an exogenous grid of \(a_t\) values that span the range of values that could plausibly be achieved, compute \(\mathfrak{v}'_t(a_t)\) at each of these points, calculate the value of consumption \(c_t\) whose marginal utility is consistent with the marginal value of assets, then find the endogenous \(m_t\) gridpoint as \(m_t = a_t + c_t\). The set of \((m_t,c_t)\) gridpoints is then interpolated to construct the consumption function.
Example parameter values to construct an instance of IndShockConsumerType#
In order to create an instance of IndShockConsumerType, the user must specify parameters that characterize the (age-varying) distribution of income shocks \(F_{t+1}\), the artificial borrowing constraint \(\underline{a}\), and the exogenous grid of end-of-period assets-above-minimum for use by EGM, along with all of the parameters for the perfect foresight model. The table below presents the complete list of parameter values required to instantiate an IndShockConsumerType, along
with example values.
Parameter |
Description |
Code |
Example value |
Time-varying? |
|---|---|---|---|---|
\(\DiscFac\) |
Intertemporal discount factor |
\(\texttt{DiscFac}\) |
\(0.96\) |
|
\(\CRRA\) |
Coefficient of relative risk aversion |
\(\texttt{CRRA}\) |
\(2.0\) |
|
\(\Rfree\) |
Risk free interest factor |
\(\texttt{Rfree}\) |
\(1.03\) |
|
\(1 - \DiePrb_{t+1}\) |
Survival probability |
\(\texttt{LivPrb}\) |
\([0.98]\) |
\(\surd\) |
\(\PermGroFac_{t+1}\) |
Permanent income growth factor |
\(\texttt{PermGroFac}\) |
\([1.01]\) |
\(\surd\) |
\(\sigma_\psi\) |
Standard deviation of log permanent income shocks |
\(\texttt{PermShkStd}\) |
\([0.1]\) |
\(\surd\) |
\(N_\psi\) |
Number of discrete permanent income shocks |
\(\texttt{PermShkCount}\) |
\(7\) |
|
\(\sigma_\theta\) |
Standard deviation of log transitory income shocks |
\(\texttt{TranShkStd}\) |
\([0.2]\) |
\(\surd\) |
\(N_\theta\) |
Number of discrete transitory income shocks |
\(\texttt{TranShkCount}\) |
\(7\) |
|
\(\mho\) |
Probability of being unemployed and getting \(\theta=\underline{\theta}\) |
\(\texttt{UnempPrb}\) |
\(0.05\) |
|
\(\underline{\theta}\) |
Transitory shock when unemployed |
\(\texttt{IncUnemp}\) |
\(0.3\) |
|
\(\mho^{Ret}\) |
Probability of being “unemployed” when retired |
\(\texttt{UnempPrbRet}\) |
\(0.0005\) |
|
\(\underline{\theta}^{Ret}\) |
Transitory shock when “unemployed” and retired |
\(\texttt{IncUnempRet}\) |
\(0.0\) |
|
\((none)\) |
Period of the lifecycle model when retirement begins |
\(\texttt{T\_retire}\) |
\(0\) |
|
\((none)\) |
Minimum value in assets-above-minimum grid |
\(\texttt{aXtraMin}\) |
\(0.001\) |
|
\((none)\) |
Maximum value in assets-above-minimum grid |
\(\texttt{aXtraMax}\) |
\(20.0\) |
|
\((none)\) |
Number of points in base assets-above-minimum grid |
\(\texttt{aXtraCount}\) |
\(48\) |
|
\((none)\) |
Exponential nesting factor for base assets-above-minimum grid |
\(\texttt{aXtraNestFac}\) |
\(3\) |
|
\((none)\) |
Additional values to add to assets-above-minimum grid |
\(\texttt{aXtraExtra}\) |
\(None\) |
|
\(\underline{a}\) |
Artificial borrowing constraint (normalized) |
\(\texttt{BoroCnstArt}\) |
\(0.0\) |
|
\((none)\) |
Indicator for whether \(\texttt{vFunc}\) should be computed |
\(\texttt{vFuncBool}\) |
\(True\) |
|
\((none)\) |
Indicator for whether \(\texttt{cFunc}\) should use cubic splines |
\(\texttt{CubicBool}\) |
\(False\) |
|
\(T\) |
Number of periods in this type’s “cycle” |
\(\texttt{T\_cycle}\) |
\(1\) |
|
(none) |
Number of times the “cycle” occurs |
\(\texttt{cycles}\) |
\(0\) |
[2]:
IdiosyncDict = {
# Parameters shared with the perfect foresight model
"CRRA": 2.0, # Coefficient of relative risk aversion
"Rfree": 1.03, # Interest factor on assets
"DiscFac": 0.96, # Intertemporal discount factor
"LivPrb": [0.98], # Survival probability
"PermGroFac": [1.01], # Permanent income growth factor
# Parameters that specify the income distribution over the lifecycle
"PermShkStd": [0.1], # Standard deviation of log permanent shocks to income
"PermShkCount": 7, # Number of points in discrete approximation to permanent income shocks
"TranShkStd": [0.2], # Standard deviation of log transitory shocks to income
"TranShkCount": 7, # Number of points in discrete approximation to transitory income shocks
"UnempPrb": 0.05, # Probability of unemployment while working
"IncUnemp": 0.3, # Unemployment benefits replacement rate
"UnempPrbRet": 0.0005, # Probability of "unemployment" while retired
"IncUnempRet": 0.0, # "Unemployment" benefits when retired
"T_retire": 0, # Period of retirement (0 --> no retirement)
"tax_rate": 0.0, # Flat income tax rate (legacy parameter, will be removed in future)
# Parameters for constructing the "assets above minimum" grid
"aXtraMin": 0.001, # Minimum end-of-period "assets above minimum" value
"aXtraMax": 20, # Maximum end-of-period "assets above minimum" value
"aXtraCount": 48, # Number of points in the base grid of "assets above minimum"
"aXtraNestFac": 3, # Exponential nesting factor when constructing "assets above minimum" grid
"aXtraExtra": None, # Additional values to add to aXtraGrid
# A few other paramaters
"BoroCnstArt": 0.0, # Artificial borrowing constraint; imposed minimum level of end-of period assets
"vFuncBool": True, # Whether to calculate the value function during solution
"CubicBool": False, # Preference shocks currently only compatible with linear cFunc
"T_cycle": 1, # Number of periods in the cycle for this agent type
# Parameters only used in simulation
"AgentCount": 10000, # Number of agents of this type
"T_sim": 120, # Number of periods to simulate
"aNrmInitMean": -6.0, # Mean of log initial assets
"aNrmInitStd": 1.0, # Standard deviation of log initial assets
"pLvlInitMean": 0.0, # Mean of log initial permanent income
"pLvlInitStd": 0.0, # Standard deviation of log initial permanent income
"PermGroFacAgg": 1.0, # Aggregate permanent income growth factor
"T_age": None, # Age after which simulated agents are automatically killed
}
The distribution of permanent income shocks is specified as mean one lognormal, with an age-varying (underlying) standard deviation. The distribution of transitory income shocks is also mean one lognormal, but with an additional point mass representing unemployment; the transitory shocks are adjusted so that the distribution is still mean one. The continuous distributions are discretized with an equiprobable distribution.
Optionally, the user can specify the period when the individual retires and escapes essentially all income risk as T_retire; this can be turned off by setting the parameter to \(0\). In retirement, all permanent income shocks are turned off, and the only transitory shock is an “unemployment” shock, likely with small probability; this prevents the retired problem from degenerating into a perfect foresight model.
The grid of assets above minimum \(\texttt{aXtraGrid}\) is specified by its minimum and maximum level, the number of gridpoints, and the extent of exponential nesting. The greater the (integer) value of \(\texttt{aXtraNestFac}\), the more dense the gridpoints will be at the bottom of the grid (and more sparse near the top); setting \(\texttt{aXtraNestFac}\) to \(0\) will generate an evenly spaced grid of \(a_t\).
The artificial borrowing constraint \(\texttt{BoroCnstArt}\) can be set to None to turn it off.
It is not necessary to compute the value function in this model, and it is not computationally free to do so. You can choose whether the value function should be calculated and returned as part of the solution of the model with \(\texttt{vFuncBool}\). The consumption function will be constructed as a piecewise linear interpolation when \(\texttt{CubicBool}\) is False, and will be a piecewise cubic spline interpolator if True.
Solving and examining the solution of the idiosyncratic income shocks model#
The cell below creates an infinite horizon instance of IndShockConsumerType and solves its model by calling its solve method.
[3]:
IndShockExample = IndShockConsumerType(**IdiosyncDict)
IndShockExample.cycles = 0 # Make this type have an infinite horizon
IndShockExample.solve()
After solving the model, we can examine an element of this type’s \(\texttt{solution}\):
[4]:
print(vars(IndShockExample.solution[0]))
{'cFunc': <HARK.interpolation.LowerEnvelope object at 0x7f90b4c9a8d0>, 'vFunc': <HARK.interpolation.ValueFuncCRRA object at 0x7f90b4c9d610>, 'vPfunc': <HARK.interpolation.MargValueFuncCRRA object at 0x7f90c08ebd10>, 'vPPfunc': <HARK.utilities.NullFunc object at 0x7f90b4c9c610>, 'mNrmMin': 0.0, 'hNrm': 44.991920196607595, 'MPCmin': 0.044536273404377116, 'MPCmax': 1.0, 'mNrmStE': 1.5488165705077037, 'mNrmTrg': 1.5799173260214134}
The single-period solution to an idiosyncratic shocks consumer’s problem has all of the same attributes as in the perfect foresight model, with a couple additions. The solution can include the marginal marginal value of market resources function \(\texttt{vPPfunc}\), but this is only constructed if \(\texttt{CubicBool}\) is True, so that the MPC can be accurately computed; when it is False, then \(\texttt{vPPfunc}\) merely returns NaN everywhere.
The solveConsIndShock function calculates steady state market resources and stores it in the attribute \(\texttt{mNrmSS}\). This represents the steady state level of \(m_t\) if this period were to occur indefinitely, but with income shocks turned off. This is relevant in a “one period infinite horizon” model like we’ve specified here, but is less useful in a lifecycle model.
Let’s take a look at the consumption function by plotting it, along with its derivative (the MPC):
[5]:
print("Consumption function for an idiosyncratic shocks consumer type:")
plot_funcs(IndShockExample.solution[0].cFunc, IndShockExample.solution[0].mNrmMin, 5)
print("Marginal propensity to consume for an idiosyncratic shocks consumer type:")
plot_funcs_der(
IndShockExample.solution[0].cFunc,
IndShockExample.solution[0].mNrmMin,
5,
)
Consumption function for an idiosyncratic shocks consumer type:
Marginal propensity to consume for an idiosyncratic shocks consumer type:
The lower part of the consumption function is linear with a slope of 1, representing the constrained part of the consumption function where the consumer would like to consume more by borrowing– his marginal utility of consumption exceeds the marginal value of assets– but he is prevented from doing so by the artificial borrowing constraint.
The MPC is a step function, as the \(\texttt{cFunc}\) itself is a piecewise linear function; note the large jump in the MPC where the borrowing constraint begins to bind.
If you want to look at the interpolation nodes for the consumption function, these can be found by “digging into” attributes of \(\texttt{cFunc}\):
[6]:
print(
"mNrmGrid for unconstrained cFunc is ",
IndShockExample.solution[0].cFunc.functions[0].x_list,
)
print(
"cNrmGrid for unconstrained cFunc is ",
IndShockExample.solution[0].cFunc.functions[0].y_list,
)
print(
"mNrmGrid for borrowing constrained cFunc is ",
IndShockExample.solution[0].cFunc.functions[1].x_list,
)
print(
"cNrmGrid for borrowing constrained cFunc is ",
IndShockExample.solution[0].cFunc.functions[1].y_list,
)
mNrmGrid for unconstrained cFunc is [-0.25017509 -0.23682357 -0.04309334 0.08570877 0.19249704 0.28773035
0.37527975 0.4572262 0.53458817 0.60902763 0.68157147 0.75266421
0.82159155 0.89091324 0.96108615 1.03297006 1.10702535 1.18386894
1.26405846 1.34797683 1.43498517 1.52575439 1.62247992 1.7264799
1.83886328 1.96091089 2.09399047 2.23965509 2.39978161 2.57666105
2.77296758 2.99185309 3.23706867 3.51312387 3.82546834 4.18073875
4.58704087 5.05438059 5.59517832 6.2249668 6.96332613 7.83514604
8.87231638 10.11613869 11.62057399 13.45688075 15.72024305 18.53939481
22.09098021]
cNrmGrid for unconstrained cFunc is [0. 0.01235151 0.18691037 0.29541926 0.38070319 0.45312275
0.51644051 0.57261755 0.62253956 0.66772112 0.70902525 0.74671381
0.77986847 0.81082056 0.8397706 0.86728992 0.89351353 0.91869035
0.94296058 0.9662323 0.98732483 1.00628889 1.02460772 1.04277873
1.06096172 1.07933575 1.0979846 1.11695897 1.13637025 1.15642563
1.17732806 1.19928447 1.22251841 1.24729118 1.27390725 1.30273462
1.33419368 1.3688058 1.40720505 1.45016983 1.49866721 1.55391366
1.61742883 1.69119491 1.77777206 1.88053049 2.00400672 2.15448643
2.3411553 ]
mNrmGrid for borrowing constrained cFunc is [0. 1.]
cNrmGrid for borrowing constrained cFunc is [0. 1.]
The consumption function in this model is an instance of LowerEnvelope1D, a class that takes an arbitrary number of 1D interpolants as arguments to its initialization method. When called, a LowerEnvelope1D evaluates each of its component functions and returns the lowest value. Here, the two component functions are the unconstrained consumption function– how the agent would consume if the artificial borrowing constraint did not exist for just this period– and the borrowing
constrained consumption function– how much he would consume if the artificial borrowing constraint is binding.
The actual consumption function is the lower of these two functions, pointwise. We can see this by plotting the component functions on the same figure:
[7]:
plot_funcs(IndShockExample.solution[0].cFunc.functions, -0.25, 5.0)
Simulating the idiosyncratic income shocks model#
In order to generate simulated data, an instance of IndShockConsumerType needs to know how many agents there are that share these particular parameters (and are thus ex ante homogeneous), the distribution of states for newly “born” agents, and how many periods to simulate. These simulation parameters are described in the table below, along with example values.
Description |
Code |
Example value |
|---|---|---|
Number of consumers of this type |
\(\texttt{AgentCount}\) |
\(10000\) |
Number of periods to simulate |
\(\texttt{T\_sim}\) |
\(120\) |
Mean of initial log (normalized) assets |
\(\texttt{aNrmInitMean}\) |
\(-6.0\) |
Stdev of initial log (normalized) assets |
\(\texttt{aNrmInitStd}\) |
\(1.0\) |
Mean of initial log permanent income |
\(\texttt{pLvlInitMean}\) |
\(0.0\) |
Stdev of initial log permanent income |
\(\texttt{pLvlInitStd}\) |
\(0.0\) |
Aggregrate productivity growth factor |
\(\texttt{PermGroFacAgg}\) |
\(1.0\) |
Age after which consumers are automatically killed |
\(\texttt{T\_age}\) |
\(None\) |
Here, we will simulate 10,000 consumers for 120 periods. All newly born agents will start with permanent income of exactly \(P_t = 1.0 = \exp(\texttt{pLvlInitMean})\), as \(\texttt{pLvlInitStd}\) has been set to zero; they will have essentially zero assets at birth, as \(\texttt{aNrmInitMean}\) is \(-6.0\); assets will be less than \(1\%\) of permanent income at birth.
These example parameter values were already passed as part of the parameter dictionary that we used to create IndShockExample, so it is ready to simulate. We need to set the track_vars attribute to indicate the variables for which we want to record a history.
[8]:
IndShockExample.track_vars = ["aNrm", "mNrm", "cNrm", "pLvl"]
IndShockExample.initialize_sim()
IndShockExample.simulate()
[8]:
{'aNrm': array([[0.14602862, 0.14694881, 0.14597285, ..., 0.14631576, 0.14556721,
0.148584 ],
[0.23850959, 0.38800208, 0. , ..., 0.54873336, 0.31064458,
0.08310162],
[0.2976058 , 0.28272742, 0. , ..., 0.3667511 , 0.31213742,
0.11393198],
...,
[0.70595038, 0.24814475, 0.63035211, ..., 0.14775242, 0.27161768,
0.78005334],
[0.57148698, 0.2518168 , 0.14574918, ..., 0.5500262 , 0.62585632,
0.9087781 ],
[0.38435613, 0.1524396 , 0.53814767, ..., 0.48933509, 0.65760681,
1.13983997]]),
'mNrm': array([[1.00112871, 1.00261969, 1.00103835, ..., 1.00159396, 1.0003811 ,
1.00526919],
[1.14420434, 1.35623674, 0.47504483, ..., 1.56186035, 1.24906819,
0.89603531],
[1.23037028, 1.20903435, 0.3 , ..., 1.32723002, 1.25120896,
0.94851723],
...,
[1.75302376, 1.15853464, 1.66183621, ..., 1.00392178, 1.19310273,
1.84139642],
[1.5899301 , 1.16399605, 1.00067594, ..., 1.56345525, 1.65638861,
1.99254713],
[1.35142412, 1.01151641, 1.54880143, ..., 1.4876664 , 1.69486106,
2.25916388]]),
'cNrm': array([[0.85510009, 0.85567088, 0.8550655 , ..., 0.8552782 , 0.85481388,
0.85668519],
[0.90569475, 0.96823466, 0.47504483, ..., 1.01312699, 0.93842361,
0.81293369],
[0.93276448, 0.92630693, 0.3 , ..., 0.96047892, 0.93907154,
0.83458526],
...,
[1.04707338, 0.91038989, 1.0314841 , ..., 0.85616936, 0.92148505,
1.06134308],
[1.01844311, 0.91217925, 0.85492676, ..., 1.01342905, 1.03053229,
1.08376904],
[0.96706799, 0.85907682, 1.01065377, ..., 0.99833131, 1.03725425,
1.11932391]]),
'pLvl': array([[0.85893446, 1.08875607, 1.08875607, ..., 1.17807023, 1.17807023,
0.85893446],
[1.01188512, 1.01015813, 0.93517011, ..., 1.09302465, 1.14116783,
0.86324343],
[0.869143 , 0.86765963, 0.93986152, ..., 1.05878626, 1.18993864,
0.90013641],
...,
[1.22431225, 0.70948837, 1.78342293, ..., 0.96867555, 1.05861408,
4.7408147 ],
[1.23045419, 0.60940401, 1.08875607, ..., 0.8987463 , 1.1525725 ,
4.76459769],
[1.19191089, 0.59031477, 1.09421797, ..., 0.93715659, 0.98998424,
5.18748464]])}
We can now look at the simulated data in aggregate or at the individual consumer level. Like in the perfect foresight model, we can plot average (normalized) market resources over time, as well as average consumption:
[9]:
plt.plot(np.mean(IndShockExample.history["mNrm"], axis=1))
plt.xlabel("Time")
plt.ylabel("Mean market resources")
plt.show()
plt.plot(np.mean(IndShockExample.history["cNrm"], axis=1))
plt.xlabel("Time")
plt.ylabel("Mean consumption")
plt.show()
We could also plot individual consumption paths for some of the consumers– say, the first five:
[10]:
plt.plot(IndShockExample.history["cNrm"][:, 0:5])
plt.xlabel("Time")
plt.ylabel("Individual consumption paths")
plt.show()
