ConsRiskyContribModel¶
This file contains classes and functions for representing, solving, and simulating a consumer type with idiosyncratic shocks to permanent and transitory income, who can save in both a risk-free and a risky asset but faces frictions to moving funds between them. The agent can only consume out of his risk-free asset.
The model is described in detail in the REMARK: https://econ-ark.org/materials/riskycontrib
- @software{mateo_velasquez_giraldo_2021_4977915,
author = {Mateo Velásquez-Giraldo}, title = {{Mv77/RiskyContrib: A Two-Asset Savings Model with
an Income-Contribution Scheme}},
month = jun, year = 2021, publisher = {Zenodo}, version = {v1.0.1}, doi = {10.5281/zenodo.4977915}, url = {https://doi.org/10.5281/zenodo.4977915}
}
- class HARK.ConsumptionSaving.ConsRiskyContribModel.RiskyContribCnsSolution(vFunc=None, cFunc=None, dvdmFunc=None, dvdnFunc=None, dvdsFunc=None)¶
Bases:
MetricObject
A class for representing the solution to the consumption stage of the ‘RiskyContrib’ model.
- Parameters:
vFunc (ValueFunc3D) – Stage-value function over normalized liquid resources, normalized iliquid resources, and income contribution share.
cFunc (Interp3D) – Consumption function over normalized liquid resources, normalized iliquid resources, and income contribution share.
dvdmFunc (MargValueFunc3D) – Marginal value function over normalized liquid resources.
dvdnFunc (MargValueFunc3D) – Marginal value function over normalized iliquid resources.
dvdsFunc (Interp3D) – Marginal value function over income contribution share.
- distance_criteria = ['dvdmFunc', 'dvdnFunc']¶
- class HARK.ConsumptionSaving.ConsRiskyContribModel.RiskyContribConsumerType(verbose=False, quiet=False, joint_dist_solver=False, **kwds)¶
Bases:
IndShockRiskyAssetConsumerType
A consumer type with idiosyncratic shocks to permanent and transitory income, who can save in both a risk-free and a risky asset but faces frictions to moving funds between them. The agent can only consume out of his risk-free asset.
- The frictions are:
A proportional tax on funds moved from the risky to the risk-free
asset.
A stochastic inability to move funds between his accounts.
To partially avoid the second friction, the agent can commit to have a fraction of his labor income, which is usually deposited in his risk-free account, diverted to his risky account. He can change this fraction only in periods where he is able to move funds between accounts.
- get_controls_Cns()¶
Get controls for the third “stage”: consumption.
- get_controls_Reb()¶
Get controls for the first stage: rebalancing
- get_controls_Sha()¶
Get controls for the second “stage”: choosing the contribution share.
- get_post_states()¶
Set variables that are not a state to any problem but need to be computed in order to interact with shocks and produce next period’s states.
- get_states_Cns()¶
Get states for the third “stage”: consumption.
- get_states_Reb()¶
Get states for the first “stage”: rebalancing.
- get_states_Sha()¶
Get states for the second “stage”: choosing the contribution share.
- initialize_sim()¶
Initialize the state of simulation attributes.
- 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
- shock_vars_ = ['PermShk', 'TranShk', 'Adjust', 'Risky']¶
- sim_birth(which_agents)¶
Create new agents to replace ones who have recently died; takes draws of initial aNrm and pLvl, as in ConsIndShockModel, then sets Share, Adjust and post-rebalancing risky asset nNrmTilde to zero as initial values. :param which_agents: Boolean array of size AgentCount indicating which agents should be “born”. :type which_agents: np.array
- Return type:
None
- sim_one_period()¶
Simulates one period for this type.
Has to be re-defined instead of using AgentType.sim_one_period() because of the “stages” structure.
- Parameters:
None –
- Return type:
None
- state_vars = ['pLvl', 'PlvlAgg', 'bNrm', 'mNrm', 'aNrm', 'aLvl', 'gNrm', 'nNrm', 'mNrmTilde', 'nNrmTilde', 'Share']¶
- time_inv_ = ['CRRA', 'DiscFac', 'BoroCnstArt', 'BoroCnstArt', 'vFuncBool', 'CubicBool', 'PortfolioBisect', 'DiscreteShareBool', 'joint_dist_solver']¶
- update()¶
Update the income process, the assets grid, and the terminal solution.
- Parameters:
None –
- Return type:
None
- update_dfrac_grid()¶
Creates grid for the rebalancing flow between assets. This flow is normalized as a ratio. - If d > 0, d*mNrm flows towards the risky asset. - If d < 0, d*nNrm (pre-tax) flows towards the risk-free asset.
- Return type:
None.
- update_mNrm_grid()¶
Updates the agent’s liquid assets exogenous grid by constructing a multi-exponentially spaced grid of mNrm values.
- Parameters:
None –
- Return type:
None.
- update_nNrm_grid()¶
Updates the agent’s iliquid assets grid by constructing a multi-exponentially spaced grid of nNrm values.
- Parameters:
None –
- Return type:
None.
Creates grid for the income contribution share.
- Parameters:
None –
- Return type:
None
- update_solution_terminal()¶
Solves the terminal period. The solution is trivial. Cns: agent will consume all of his liquid resources. Sha: irrelevant as there is no “next” period. Reb: agent will shift all of his resources to the risk-free asset.
- Parameters:
None –
- Return type:
None
- update_tau()¶
Checks that the tax rate on risky-to-risk-free flows has the appropriate length adds it to time_(in)vary
- Return type:
None.
- class HARK.ConsumptionSaving.ConsRiskyContribModel.RiskyContribRebSolution(vFunc_Adj=None, dfracFunc_Adj=None, dvdmFunc_Adj=None, dvdnFunc_Adj=None, vFunc_Fxd=None, dfracFunc_Fxd=None, dvdmFunc_Fxd=None, dvdnFunc_Fxd=None, dvdsFunc_Fxd=None)¶
Bases:
MetricObject
A class for representing the solution to the asset-rebalancing stage of the ‘RiskyContrib’ model.
- Parameters:
vFunc_Adj (ValueFunc2D) – Stage value function over normalized liquid resources and normalized iliquid resources when the agent is able to adjust his portfolio.
dfracFunc_Adj (Interp2D) – Deposit function over normalized liquid resources and normalized iliquid resources when the agent is able to adjust his portfolio.
dvdmFunc_Adj (MargValueFunc2D) – Marginal value over normalized liquid resources when the agent is able to adjust his portfolio.
dvdnFunc_Adj (MargValueFunc2D) – Marginal value over normalized liquid resources when the agent is able to adjust his portfolio.
vFunc_Fxd (ValueFunc3D) – Stage value function over normalized liquid resources, normalized iliquid resources, and income contribution share when the agent is not able to adjust his portfolio.
dfracFunc_Fxd (Interp2D) – Deposit function over normalized liquid resources, normalized iliquid resources, and income contribution share when the agent is not able to adjust his portfolio. Must be ConstantFunction(0.0)
dvdmFunc_Fxd (MargValueFunc3D) – Marginal value over normalized liquid resources when the agent is not able to adjust his portfolio.
dvdnFunc_Fxd (MargValueFunc3D) – Marginal value over normalized iliquid resources when the agent is not able to adjust his portfolio.
dvdsFunc_Fxd (Interp3D) – Marginal value function over income contribution share when the agent is not able to ajust his portfolio.
- distance_criteria = ['dvdmFunc_Adj', 'dvdnFunc_Adj']¶
- class HARK.ConsumptionSaving.ConsRiskyContribModel.RiskyContribShaSolution(vFunc_Adj=None, ShareFunc_Adj=None, dvdmFunc_Adj=None, dvdnFunc_Adj=None, vFunc_Fxd=None, ShareFunc_Fxd=None, dvdmFunc_Fxd=None, dvdnFunc_Fxd=None, dvdsFunc_Fxd=None)¶
Bases:
MetricObject
A class for representing the solution to the contribution-share stage of the ‘RiskyContrib’ model.
- Parameters:
vFunc_Adj (ValueFunc2D) – Stage value function over normalized liquid resources and normalized iliquid resources when the agent is able to adjust his portfolio.
ShareFunc_Adj (Interp2D) – Income contribution share function over normalized liquid resources and normalized iliquid resources when the agent is able to adjust his portfolio.
dvdmFunc_Adj (MargValueFunc2D) – Marginal value function over normalized liquid resources when the agent is able to adjust his portfolio.
dvdnFunc_Adj (MargValueFunc2D) – Marginal value function over normalized iliquid resources when the agent is able to adjust his portfolio.
vFunc_Fxd (ValueFunc3D) – Stage value function over normalized liquid resources, normalized iliquid resources, and income contribution share when the agent is not able to adjust his portfolio.
ShareFunc_Fxd (Interp3D) – Income contribution share function over normalized liquid resources, iliquid resources, and income contribution share when the agent is not able to adjust his portfolio. Should be an IdentityFunc.
dvdmFunc_Fxd (MargValueFunc3D) – Marginal value function over normalized liquid resources when the agent is not able to adjust his portfolio.
dvdnFunc_Fxd (MargValueFunc3D) – Marginal value function over normalized iliquid resources when the agent is not able to adjust his portfolio.
dvdsFunc_Fxd (Interp3D) – Marginal value function over income contribution share when the agent is not able to adjust his portfolio
- distance_criteria = ['dvdmFunc_Adj', 'dvdnFunc_Adj']¶
- class HARK.ConsumptionSaving.ConsRiskyContribModel.RiskyContribSolution(Reb, Sha, Cns)¶
Bases:
MetricObject
A class for representing the solution to a full time-period of the ‘RiskyContrib’ agent type’s problem.
- Parameters:
Reb (RiskyContribRebSolution) – Solution to the period’s rebalancing stage.
Sha (RiskyContribShaSolution) – Solution to the period’s contribution-share stage.
Cns (RiskyContribCnsSolution) – Solution to the period’s consumption stage.
- distance_criteria = ['stage_sols']¶
- HARK.ConsumptionSaving.ConsRiskyContribModel.m_nrm_next(shocks, aNrm, Share, Rfree, PermGroFac)¶
Given end-of-period balances and contribution share and the start-of-next-period shocks, figure out next period’s normalized riskless assets
- Parameters:
shocks (np.array) – Length-3 array with the stochastic shocks that get realized between the end of the current period and the start of next period. Their order is (0) permanent income shock, (1) transitory income shock, (2) risky asset return.
aNrm (float) – End-of-period risk-free asset balances.
Share (float) – End-of-period income deduction share.
Rfree (float) – Risk-free return factor.
PermGroFac (float) – Permanent income growth factor.
- Returns:
m_nrm_tp1 – Next-period normalized riskless balance.
- Return type:
- HARK.ConsumptionSaving.ConsRiskyContribModel.n_nrm_next(shocks, nNrm, Share, PermGroFac)¶
Given end-of-period balances and contribution share and the start-of-next-period shocks, figure out next period’s normalized risky assets
- Parameters:
shocks (np.array) – Length-3 array with the stochastic shocks that get realized between the end of the current period and the start of next period. Their order is (0) permanent income shock, (1) transitory income shock, (2) risky asset return.
nNrm (float) – End-of-period risky asset balances.
Share (float) – End-of-period income deduction share.
PermGroFac (float) – Permanent income growth factor.
- Returns:
n_nrm_tp1 – Next-period normalized risky balance.
- Return type:
- HARK.ConsumptionSaving.ConsRiskyContribModel.rebalance_assets(d, m, n, tau)¶
A function that produces post-rebalancing assets for given initial assets, rebalancing action, and tax rate.
- Parameters:
d (np.array) – Array with rebalancing decisions. d > 0 represents depositing d*m into the risky asset account. d<0 represents withdrawing |d|*n (pre-tax) from the risky account into the risky account.
m (np.array) – Initial risk-free assets.
n (np.array) – Initial risky assets.
tau (float) – Tax rate on flows from the risky to the risk-free asset.
- Returns:
mTil (np.array) – Post-rebalancing risk-free assets.
nTil (np.arrat) – Post-rebalancing risky assets.
- HARK.ConsumptionSaving.ConsRiskyContribModel.solveRiskyContrib(solution_next, ShockDstn, IncShkDstn, RiskyDstn, IndepDstnBool, LivPrb, DiscFac, CRRA, Rfree, PermGroFac, tau, BoroCnstArt, aXtraGrid, nNrmGrid, mNrmGrid, ShareGrid, dfracGrid, vFuncBool, AdjustPrb, DiscreteShareBool, joint_dist_solver)¶
Solve a full period (with its three stages) of the agent’s problem
- Parameters:
solution_next (RiskyContribSolution) – Solution to next period’s problem.
ShockDstn (DiscreteDistribution) – Joint distribution of next period’s (0) permanent income shock, (1) transitory income shock, and (2) risky asset return factor.
IncShkDstn (DiscreteDistribution) – Joint distribution of next period’s (0) permanent income shock and (1) transitory income shock.
RiskyDstn (DiscreteDistribution) – Distribution of next period’s risky asset return factor.
IndepDstnBool (bool) – Indicates whether the income and risky return distributions are independent.
LivPrb (float) – Probability of surviving until next period.
DiscFac (float) – Time-preference discount factor.
CRRA (float) – Coefficient of relative risk aversion.
Rfree (float) – Risk-free return factor.
PermGroFac (float) – Deterministic permanent income growth factor.
tau (float) – Tax rate on risky asset withdrawals.
BoroCnstArt (float) – Minimum allowed market resources (must be 0).
aXtraGrid (numpy array) – Exogenous grid for end-of-period risk free resources.
nNrmGrid (numpy array) – Exogenous grid for risky resources.
mNrmGrid (numpy array) – Exogenous grid for risk-free resources.
ShareGrid (numpy array) – Exogenous grid for the income contribution share.
dfracGrid (numpy array) – Grid for rebalancing flows. The final grid will be equivalent to [-nNrm*dfracGrid, dfracGrid*mNrm].
vFuncBool (bool) – Determines whether the level of th value function must be computed.
AdjustPrb (float) – Probability that the agent will be able to rebalance his portfolio next period.
DiscreteShareBool (bool) – Boolean that determines whether only a discrete set of contribution shares (ShareGrid) is allowed.
joint_dist_solver (bool) – Should the general solver be used even if income and returns are independent?
- Returns:
periodSol – Solution to the agent’s current-period problem.
- Return type:
- HARK.ConsumptionSaving.ConsRiskyContribModel.solve_RiskyContrib_Cns(solution_next, ShockDstn, IncShkDstn, RiskyDstn, IndepDstnBool, LivPrb, DiscFac, CRRA, Rfree, PermGroFac, BoroCnstArt, aXtraGrid, nNrmGrid, mNrmGrid, ShareGrid, vFuncBool, AdjustPrb, DiscreteShareBool, joint_dist_solver, **unused_params)¶
Solves the consumption stage of the agent’s problem
- Parameters:
solution_next (RiskyContribRebSolution) – Solution to the first stage of the next period in the agent’s problem.
ShockDstn (DiscreteDistribution) – Joint distribution of next period’s (0) permanent income shock, (1) transitory income shock, and (2) risky asset return factor.
IncShkDstn (DiscreteDistribution) – Joint distribution of next period’s (0) permanent income shock and (1) transitory income shock.
RiskyDstn (DiscreteDistribution) – Distribution of next period’s risky asset return factor.
IndepDstnBool (bool) – Indicates whether the income and risky return distributions are independent.
LivPrb (float) – Probability of surviving until next period.
DiscFac (float) – Time-preference discount factor.
CRRA (float) – Coefficient of relative risk aversion.
Rfree (float) – Risk-free return factor.
PermGroFac (float) – Deterministic permanent income growth factor.
BoroCnstArt (float) – Minimum allowed market resources (must be 0).
aXtraGrid (numpy array) – Exogenous grid for end-of-period risk free resources.
nNrmGrid (numpy array) – Exogenous grid for risky resources.
mNrmGrid (numpy array) – Exogenous grid for risk-free resources.
ShareGrid (numpt array) – Exogenous grid for the income contribution share.
vFuncBool (bool) – Boolean that determines wether the value function’s level needs to be computed.
AdjustPrb (float) – Probability thet the agent will be able to adjust his portfolio next period.
DiscreteShareBool (bool) – Boolean that determines whether only a discrete set of contribution shares (ShareGrid) is allowed.
joint_dist_solver (bool) – Should the general solver be used even if income and returns are independent?
- Returns:
solution – Solution to the agent’s consumption stage problem.
- Return type:
- HARK.ConsumptionSaving.ConsRiskyContribModel.solve_RiskyContrib_Reb(solution_next, CRRA, tau, nNrmGrid, mNrmGrid, dfracGrid, vFuncBool, **unused_params)¶
Solves the asset-rebalancing-stage of the agent’s problem
- Parameters:
solution_next (RiskyContribShaSolution) – Solution to the income-contribution-share stage problem that follows.
CRRA (float) – Coefficient of relative risk aversion.
tau (float) – Tax rate on risky asset withdrawals.
nNrmGrid (numpy array) – Exogenous grid for risky resources.
mNrmGrid (numpy array) – Exogenous grid for risk-free resources.
dfracGrid (numpy array) – Grid for rebalancing flows. The final grid will be equivalent to [-nNrm*dfracGrid, dfracGrid*mNrm].
vFuncBool (bool) – Determines whether the level of th value function must be computed.
- Returns:
solution – Solution to the asset-rebalancing stage of the agent’s problem.
- Return type:
- HARK.ConsumptionSaving.ConsRiskyContribModel.solve_RiskyContrib_Sha(solution_next, CRRA, AdjustPrb, mNrmGrid, nNrmGrid, ShareGrid, DiscreteShareBool, vFuncBool, **unused_params)¶
Solves the income-contribution-share stag of the agent’s problem
- Parameters:
solution_next (RiskyContribCnsSolution) – Solution to the agent’s consumption stage problem that follows.
CRRA (float) – Coefficient of relative risk aversion.
AdjustPrb (float) – Probability that the agent will be able to rebalance his portfolio next period.
mNrmGrid (numpy array) – Exogenous grid for risk-free resources.
nNrmGrid (numpy array) – Exogenous grid for risky resources.
ShareGrid (numpy array) – Exogenous grid for the income contribution share.
DiscreteShareBool (bool) – Boolean that determines whether only a discrete set of contribution shares (ShareGrid) is allowed.
vFuncBool (bool) – Determines whether the level of the value function is computed.
- Yields:
solution (RiskyContribShaSolution) – Solution to the income-contribution-share stage of the agent’s problem.