ConsGenIncProcessModel¶
Classes to solve consumption-saving models with idiosyncratic shocks to income in which shocks are not necessarily fully transitory or fully permanent. Extends ConsIndShockModel by explicitly tracking persistent income as a state variable, and allows (log) persistent income to follow an AR1 process rather than random walk.
- class HARK.ConsumptionSaving.ConsGenIncProcessModel.ConsGenIncProcessSolver(solution_next, IncShkDstn, LivPrb, DiscFac, CRRA, Rfree, pLvlNextFunc, BoroCnstArt, aXtraGrid, pLvlGrid, vFuncBool, CubicBool)¶
Bases:
ConsIndShockSetup
A class for solving one period problem of a consumer who experiences persistent and transitory shocks to his income. Unlike in ConsIndShock, consumers do not necessarily have the same predicted level of p next period as this period (after controlling for growth). Instead, they have a function that translates current persistent income into expected next period persistent income (subject to shocks).
- Parameters:
solution_next (ConsumerSolution) – The solution to next period’s one period problem.
IncShkDstn (distribution.Distribution) – A discrete approximation to the income process between the period being solved and the one immediately following (in solution_next). Order: event probabilities, persistent shocks, transitory shocks.
LivPrb (float) – Survival probability; likelihood of being alive at the beginning of the succeeding period.
DiscFac (float) – Intertemporal discount factor for future utility.
CRRA (float) – Coefficient of relative risk aversion.
Rfree (float) – Risk free interest factor on end-of-period assets.
pLvlNextFunc (float) – Expected persistent income next period as a function of current pLvl.
BoroCnstArt (float or None) – Borrowing constraint for the minimum allowable assets to end the period with.
aXtraGrid (np.array) – Array of “extra” end-of-period (normalized) asset values– assets above the absolute minimum acceptable level.
pLvlGrid (np.array) – Array of persistent income levels at which to solve the problem.
vFuncBool (boolean) – An indicator for whether the value function should be computed and included in the reported solution.
CubicBool (boolean) – An indicator for whether the solver should use cubic or linear interpolation.
- add_MPC_and_human_wealth(solution)¶
Take a solution and add human wealth and the bounding MPCs to it.
- Parameters:
solution (ConsumerSolution) – The solution to this period’s consumption-saving problem.
Returns –
---------- –
solution – The solution to this period’s consumption-saving problem, but now with human wealth and the bounding MPCs.
- add_vPPfunc(solution)¶
Adds the marginal marginal value function to an existing solution, so that the next solver can evaluate vPP and thus use cubic interpolation.
- Parameters:
solution (ConsumerSolution) – The solution to this single period problem, which must include the consumption function.
- Returns:
solution – The same solution passed as input, but with the marginal marginal value function for this period added as the attribute vPPfunc.
- Return type:
- calc_EndOfPrdvP()¶
Calculates end-of-period marginal value of assets at each state space point in aLvlNow x pLvlNow. Does so by taking a weighted sum of next period marginal values across income shocks (in preconstructed grids self.mLvlNext x self.pLvlNext).
- Parameters:
None –
- Returns:
EndOfPrdVP – A 2D array of end-of-period marginal value of assets.
- Return type:
np.array
- def_BoroCnst(BoroCnstArt)¶
Defines the constrained portion of the consumption function as cFuncNowCnst, an attribute of self.
- Parameters:
BoroCnstArt (float or None) – Borrowing constraint for the minimum allowable assets to end the period with. If it is less than the natural borrowing constraint, then it is irrelevant; BoroCnstArt=None indicates no artificial bor- rowing constraint.
- Return type:
None
- get_points_for_interpolation(EndOfPrdvP, aLvlNow)¶
Finds endogenous interpolation points (c,m) for the consumption function.
- Parameters:
EndOfPrdvP (np.array) – Array of end-of-period marginal values.
aLvlNow (np.array) – Array of end-of-period asset values that yield the marginal values in EndOfPrdvP.
- Returns:
c_for_interpolation (np.array) – Consumption points for interpolation.
m_for_interpolation (np.array) – Corresponding market resource points for interpolation.
- m_lvl_next(tsi, a_lvl, p_lvl_next)¶
- make_EndOfPrdvFunc(EndOfPrdvP)¶
Construct the end-of-period value function for this period, storing it as an attribute of self for use by other methods.
- Parameters:
EndOfPrdvP (np.array) – Array of end-of-period marginal value of assets corresponding to the asset values in self.aLvlNow x self.pLvlGrid.
- Return type:
none
- make_basic_solution(EndOfPrdvP, aLvl, pLvl, interpolator)¶
Given end of period assets and end of period marginal value, construct the basic solution for this period.
- Parameters:
EndOfPrdvP (np.array) – Array of end-of-period marginal values.
aLvl (np.array) – Array of end-of-period asset values that yield the marginal values in EndOfPrdvP.
pLvl (np.array) – Array of persistent income levels that yield the marginal values in EndOfPrdvP (corresponding pointwise to aLvl).
interpolator (function) – A function that constructs and returns a consumption function.
- Returns:
solution_now – The solution to this period’s consumption-saving problem, with a consumption function, marginal value function, and minimum m.
- Return type:
- make_cubic_cFunc(mLvl, pLvl, cLvl)¶
Makes a quasi-cubic spline interpolation of the unconstrained consumption function for this period. Function is cubic splines with respect to mLvl, but linear in pLvl.
- Parameters:
mLvl (np.array) – Market resource points for interpolation.
pLvl (np.array) – Persistent income level points for interpolation.
cLvl (np.array) – Consumption points for interpolation.
- Returns:
cFuncUnc – The unconstrained consumption function for this period.
- Return type:
- make_linear_cFunc(mLvl, pLvl, cLvl)¶
Makes a quasi-bilinear interpolation to represent the (unconstrained) consumption function.
- Parameters:
mLvl (np.array) – Market resource points for interpolation.
pLvl (np.array) – Persistent income level points for interpolation.
cLvl (np.array) – Consumption points for interpolation.
- Returns:
cFuncUnc – The unconstrained consumption function for this period.
- Return type:
- make_vFunc(solution)¶
Creates the value function for this period, defined over market resources m and persistent income p. self must have the attribute EndOfPrdvFunc in order to execute.
- Parameters:
solution (ConsumerSolution) – The solution to this single period problem, which must include the consumption function.
- Returns:
vFuncNow – A representation of the value function for this period, defined over market resources m and persistent income p: v = vFuncNow(m,p).
- Return type:
- make_vPfunc(cFunc)¶
Constructs the marginal value function for this period.
- Parameters:
cFunc (function) – Consumption function this period, defined over market resources and persistent income level.
- Returns:
vPfunc – Marginal value (of market resources) function for this period.
- Return type:
function
- p_lvl_next(psi, p_lvl)¶
- prepare_to_calc_EndOfPrdvP()¶
Prepare to calculate end-of-period marginal value by creating an array of market resources that the agent could have next period, considering the grid of end-of-period normalized assets, the grid of persistent income levels, and the distribution of shocks he might experience next period.
- Parameters:
None –
- Returns:
aLvlNow (np.array) – 2D array of end-of-period assets; also stored as attribute of self.
pLvlNow (np.array) – 2D array of persistent income levels this period.
- set_and_update_values(solution_next, IncShkDstn, LivPrb, DiscFac)¶
Unpacks some of the inputs (and calculates simple objects based on them), storing the results in self for use by other methods. These include: income shocks and probabilities, next period’s marginal value function (etc), the probability of getting the worst income shock next period, the patience factor, human wealth, and the bounding MPCs. Human wealth is stored as a function of persistent income.
- Parameters:
solution_next (ConsumerSolution) – The solution to next period’s one period problem.
IncShkDstn (distribution.Distribution) – A discrete approximation to the income process between the period being solved and the one immediately following (in solution_next).
LivPrb (float) – Survival probability; likelihood of being alive at the beginning of the succeeding period.
DiscFac (float) – Intertemporal discount factor for future utility.
- Return type:
None
- solve()¶
Solves a one period consumption saving problem with risky income, with persistent income explicitly tracked as a state variable.
- Parameters:
None –
- Returns:
solution – The solution to the one period problem, including a consumption function (defined over market resources and persistent income), a marginal value function, bounding MPCs, and human wealth as a func- tion of persistent income. Might also include a value function and marginal marginal value function, depending on options selected.
- Return type:
- use_points_for_interpolation(cLvl, mLvl, pLvl, interpolator)¶
Constructs a basic solution for this period, including the consumption function and marginal value function.
- Parameters:
cLvl (np.array) – Consumption points for interpolation.
mLvl (np.array) – Corresponding market resource points for interpolation.
pLvl (np.array) – Corresponding persistent income level points for interpolation.
interpolator (function) – A function that constructs and returns a consumption function.
- Returns:
solution_now – The solution to this period’s consumption-saving problem, with a consumption function, marginal value function, and minimum m.
- Return type:
- class HARK.ConsumptionSaving.ConsGenIncProcessModel.GenIncProcessConsumerType(**kwds)¶
Bases:
IndShockConsumerType
A consumer type with idiosyncratic shocks to persistent and transitory income. His problem is defined by a sequence of income distributions, survival prob- abilities, and persistent income growth functions, as well as time invariant values for risk aversion, discount factor, the interest rate, the grid of end-of-period assets, and an artificial borrowing constraint.
See init_explicit_perm_inc for a dictionary of the keywords that should be passed to the constructor.
- Parameters:
cycles (int) – Number of times the sequence of periods should be solved.
- cFunc_terminal_ = <HARK.interpolation.BilinearInterp object>¶
- get_controls()¶
Calculates consumption for each consumer of this type using the consumption functions.
- Parameters:
None –
- Return type:
None
- get_poststates()¶
Calculates end-of-period assets for each consumer of this type. Identical to version in IndShockConsumerType but uses Lvl rather than Nrm variables.
- Parameters:
None –
- Return type:
None
- install_retirement_func()¶
Installs a special pLvlNextFunc representing retirement in the correct element of self.pLvlNextFunc. Draws on the attributes T_retire and pLvlNextFuncRet. If T_retire is zero or pLvlNextFuncRet does not exist, this method does nothing. Should only be called from within the method update_pLvlNextFunc, which ensures that time is flowing forward.
- Parameters:
None –
- Return type:
None
- pre_solve()¶
A method that is run immediately before the model is solved, to check inputs or to prepare the terminal solution, perhaps.
- Parameters:
none –
- Return type:
none
- sim_birth(which_agents)¶
Makes new consumers for the given indices. Initialized variables include aNrm and pLvl, as well as time variables t_age and t_cycle. Normalized assets and persistent income levels are drawn from lognormal distributions given by aNrmInitMean and aNrmInitStd (etc).
- Parameters:
which_agents (np.array(Bool)) – Boolean array of size self.AgentCount indicating which agents should be “born”.
- Return type:
None
- solution_terminal_ = <HARK.ConsumptionSaving.ConsIndShockModel.ConsumerSolution object>¶
- state_vars = ['pLvl', 'mLvl', 'aLvl']¶
- transition()¶
Calculates updated values of normalized market resources and persistent income level for each agent. Uses pLvlNow, aLvlNow, PermShkNow, TranShkNow.
- Parameters:
None –
- Returns:
pLvlNow
mLvlNow
- update()¶
Update the income process, the assets grid, the persistent income grid, and the terminal solution.
- Parameters:
None –
- Return type:
None
- update_pLvlGrid()¶
Update the grid of persistent income levels. Currently only works for infinite horizon models (cycles=0) and lifecycle models (cycles=1). Not clear what to do about cycles>1 because the distribution of persistent income will be different within a period depending on how many cycles have elapsed. This method uses a simulation approach to generate the pLvlGrid at each period of the cycle, drawing on the initial distribution of persistent income, the pLvlNextFuncs, and the attribute pLvlPctiles.
- Parameters:
None –
- Return type:
None
- update_pLvlNextFunc()¶
A dummy method that creates a trivial pLvlNextFunc attribute that has no persistent income dynamics. This method should be overwritten by subclasses in order to make (e.g.) an AR1 income process.
- Parameters:
None –
- Return type:
None
- update_solution_terminal()¶
Update the terminal period solution. This method should be run when a new AgentType is created or when CRRA changes.
- Parameters:
None –
- Return type:
None
- class HARK.ConsumptionSaving.ConsGenIncProcessModel.IndShockExplicitPermIncConsumerType(**kwds)¶
Bases:
GenIncProcessConsumerType
A consumer type with idiosyncratic shocks to permanent and transitory income. The problem is defined by a sequence of income distributions, survival prob- abilities, and permanent income growth rates, as well as time invariant values for risk aversion, discount factor, the interest rate, the grid of end-of- period assets, and an artificial borrowing constraint. This agent type is identical to an IndShockConsumerType but for explicitly tracking pLvl as a state variable during solution. There is no real economic use for it.
- update_pLvlNextFunc()¶
A method that creates the pLvlNextFunc attribute as a sequence of linear functions, indicating constant expected permanent income growth across permanent income levels. Draws on the attribute PermGroFac, and installs a special retirement function when it exists.
- Parameters:
None –
- Return type:
None
- class HARK.ConsumptionSaving.ConsGenIncProcessModel.PersistentShockConsumerType(**kwds)¶
Bases:
GenIncProcessConsumerType
Type with idiosyncratic shocks to persistent (‘Prst’) and transitory income. The problem is defined by a sequence of income distributions, survival prob- abilities, and persistent income growth rates, as well as time invariant values for risk aversion, discount factor, the interest rate, the grid of end-of- period assets, an artificial borrowing constraint, and the AR1 correlation coefficient for (log) persistent income.
- update_pLvlNextFunc()¶
A method that creates the pLvlNextFunc attribute as a sequence of AR1-style functions. Draws on the attributes PermGroFac and PrstIncCorr. If cycles=0, the product of PermGroFac across all periods must be 1.0, otherwise this method is invalid.
- Parameters:
None –
- Return type:
None
- class HARK.ConsumptionSaving.ConsGenIncProcessModel.pLvlFuncAR1(pLogMean, PermGroFac, Corr)¶
Bases:
MetricObject
A class for representing AR1-style persistent income growth functions.