Skip to content

Commit

Permalink
Adds ConsPortfolioModel's updated documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@DominicWC
DominicWC committed Aug 20, 2024
1 parent b15ce15 commit 42e3df5
Showing 1 changed file with 158 additions and 179 deletions.
337 changes: 158 additions & 179 deletions HARK/ConsumptionSaving/ConsPortfolioModel.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1004,7 +1004,7 @@ def solve_one_period_ConsPortfolio(
###############################################################################

# Make a dictionary of constructors for the portfolio choice consumer type
portfolio_constructor_dict = {
PortfolioConsumerType_constructors_default = {
"IncShkDstn": construct_lognormal_income_process_unemployment,
"PermShkDstn": get_PermShkDstn_from_IncShkDstn,
"TranShkDstn": get_TranShkDstn_from_IncShkDstn,
Expand All @@ -1017,7 +1017,7 @@ def solve_one_period_ConsPortfolio(
}

# Default parameters to make IncShkDstn using construct_lognormal_income_process_unemployment
default_IncShkDstn_params = {
PortfolioConsumerType_IncShkDstn_default = {
"PermShkStd": [0.1], # Standard deviation of log permanent income shocks
"PermShkCount": 7, # Number of points in discrete approximation to permanent income shocks
"TranShkStd": [0.1], # Standard deviation of log transitory income shocks
Expand All @@ -1030,7 +1030,7 @@ def solve_one_period_ConsPortfolio(
}

# Default parameters to make aXtraGrid using make_assets_grid
default_aXtraGrid_params = {
PortfolioConsumerType_aXtraGrid_default = {
"aXtraMin": 0.001, # Minimum end-of-period "assets above minimum" value
"aXtraMax": 100, # Maximum end-of-period "assets above minimum" value
"aXtraNestFac": 1, # Exponential nesting factor for aXtraGrid
Expand All @@ -1039,19 +1039,21 @@ def solve_one_period_ConsPortfolio(
}

# Default parameters to make RiskyDstn with make_lognormal_RiskyDstn (and uniform ShareGrid)
default_RiskyDstn_and_ShareGrid_params = {
PortfolioConsumerType_RiskyDstn_default = {
"RiskyAvg": 1.08, # Mean return factor of risky asset
"RiskyStd": 0.18362634887, # Stdev of log returns on risky asset
"RiskyCount": 5, # Number of integration nodes to use in approximation of risky returns
"ShareCount": 25, # Number of discrete points in the risky share approximation
}
PortfolioConsumerType_ShareGrid_default = {
"ShareCount": 25 # Number of discrete points in the risky share approximation
}

# Make a dictionary to specify a risky asset consumer type
init_portfolio = {
PortfolioConsumerType_solving_default = {
# BASIC HARK PARAMETERS REQUIRED TO SOLVE THE MODEL
"cycles": 1, # Finite, non-cyclic model
"T_cycle": 1, # Number of periods in the cycle for this agent type
"constructors": portfolio_constructor_dict, # See dictionary above
"constructors": PortfolioConsumerType_constructors_default, # See dictionary above
# PRIMITIVE RAW PARAMETERS REQUIRED TO SOLVE THE MODEL
"CRRA": 5.0, # Coefficient of relative risk aversion
"Rfree": 1.03, # Return factor on risk free asset
Expand All @@ -1065,6 +1067,8 @@ def solve_one_period_ConsPortfolio(
# (Uses linear spline interpolation for cFunc when False)
"AdjustPrb": 1.0, # Probability that the agent can update their risky portfolio share each period
"sim_common_Rrisky": True, # Whether risky returns have a shared/common value across agents
}
PortfolioConsumerType_simulation_default = {
# PARAMETERS REQUIRED TO SIMULATE THE MODEL
"AgentCount": 10000, # Number of agents of this type
"T_age": None, # Age after which simulated agents are automatically killed
Expand All @@ -1080,189 +1084,164 @@ def solve_one_period_ConsPortfolio(
# (Forces Newborns to follow solution path of the agent they replaced if True)
"neutral_measure": False, # Whether to use permanent income neutral measure (see Harmenberg 2021)
}
init_portfolio.update(default_IncShkDstn_params)
init_portfolio.update(default_aXtraGrid_params)
init_portfolio.update(default_RiskyDstn_and_ShareGrid_params)
PortfolioConsumerType_default = {}
PortfolioConsumerType_default.update(PortfolioConsumerType_solving_default)
PortfolioConsumerType_default.update(PortfolioConsumerType_simulation_default)
PortfolioConsumerType_default.update(PortfolioConsumerType_aXtraGrid_default)
PortfolioConsumerType_default.update(PortfolioConsumerType_ShareGrid_default)
PortfolioConsumerType_default.update(PortfolioConsumerType_IncShkDstn_default)
PortfolioConsumerType_default.update(PortfolioConsumerType_RiskyDstn_default)
init_portfolio = PortfolioConsumerType_default


class PortfolioConsumerType(RiskyAssetConsumerType):
r"""
A consumer type based on IndShockRiskyAssetConsumerType, with portfolio optimization.
The agent is only able to change their risky asset share with a certain probability.
.. math::
\newcommand{\CRRA}{\rho}
\newcommand{\DiePrb}{\mathsf{D}}
\newcommand{\PermGroFac}{\Gamma}
\newcommand{\Rfree}{\mathsf{R}}
\newcommand{\DiscFac}{\beta}
\begin{align*}
v_t(m_t,S_t) &= \max_{c_t,S^{*}_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},S_{t+1}) \right], \\
& \text{s.t.} \\
a_t &= m_t - c_t, \\
a_t &\geq \underline{a}, \\
m_{t+1} &= \mathsf{R}_{t+1}/(\PermGroFac_{t+1} \psi_{t+1}) a_t + \theta_{t+1}, \\
\mathsf{R}_{t+1} &=S_t\phi_{t+1}\mathbf{R}_{t+1}+ (1-S_t)\mathsf{R}_{t+1}, \\
S_{t+1} &= \begin{cases}
S^{*}_t & \text{if } p_t < \wp\\
S_t & \text{if } p_t \geq \wp,
\end{cases}\\
(\psi_{t+1},\theta_{t+1},\phi_{t+1},p_t) &\sim F_{t+1}, \\
\mathbb{E}[\psi]=\mathbb{E}[\theta] &= 1.
\end{align*}
Default Shock Generator:
------------------------
Created by :class:`HARK.Calibration.Income.IncomeProcesses.construct_lognormal_income_process_unemployment`
PermShkStd: list[float], default=[0.1], time varying
Standard deviation of log permanent income shocks.
PermShkCount: int, default=7
Number of points in discrete approximation to permanent income shocks.
TranShkStd: list[float], default=[0.1], time varying
Standard deviation of log transitory income shocks.
TranShkCount: int, default=7
Number of points in discrete approximation to transitory income shocks.
UnempPrb: float or list[float], default=0.05, time varying
Probability of unemployment while working. Pass a list of floats to make UnempPrb time varying.
IncUnemp: float or list[float], default=0.3, time varying
Unemployement benefits replacement rate while working. Pass a list of floats to make IncUnemp time varying.
T_retire: int, default=0
Period of retirement (0 --> no retirement).
UnempPrbRet: float or None, default=0.005
Probability of "unemployement" while retired.
IncUnempRet: float, default=0.0
"Unemployment" benefits while retired.
neutral_measure: boolean, default=False
Whether to use permanent income neutral measure (see Harmenberg 2021).
Created by :class:`Hark.Calibration.Assets.AssetProcesses.make_lognormal_RiskyDstn`
RiskyAvg: float or list[float], default=1.08, time varying, :math:`\mathsbf{R}`
Mean return factor of risky asset. Pass a list of floats to make RiskyAvg time varying.
RiskyStd: float or list[float], default=0.2, time varying
Standard Deviation of log returns on risky assets. Pass a list of floats to make RiskyStd time varying.
RiskyCount: int, default=5
Number of integration nodes to use in approximation of risky returns.
Grid Parameters:
----------------
Created by :class:`HARK.utilities.make_assets_grid`
aXtraMin: float, default=0.001
Minimum end-of-period "assets above minimum" value.
aXtraMax: float, default=100
Maximum end-of-period "assets above minimum" value.
aXtraNestFac: int, default=1
Exponential nesting factor for aXtraGrid.
aXtraCount: int, default=200
Number of points in the grid of "assets above minimum".
aXtraExtra: list, default=None
Additional values to add in grid, None to ignore.
Created by :class:`HARK.ConsumptionSaving.ConsRiskyAssetModel.make_simple_ShareGrid`
ShareCount: int, default=25
Number of Discrete points in the risky share approximation.
Solving Parameters:
-------------------
cycles: int, default=1
0 specifies an infinite horizon model, 1 specifies a finite model.
T_cycle: int, default=1
Number of periods in the cycle for this agent type.
CRRA: float, default=5.0, :math:`\rho`
Coefficient of Relative Risk Aversion.
Rfree: float or list[float], default=1.03, time varying, :math:`\mathsf{R}`
Risk Free interest rate. Pass a list of floats to make Rfree time varying.
DiscFac: float, default=0.9, :math:`\beta`
Intertemporal discount factor.
LivPrb: list[float], default=[0.98], time varying, :math:`1-\mathsf{D}`
Survival probability after each period.
PermGroFac: list[float], default=[1.01], time varying, :math:`\Gamma`
Permanent income growth factor.
BoroCnstArt: float, default=0.0, :math:`\underline{a}`
The minimum Asset/Perminant Income ratio, None to ignore.
vFuncBool: bool, default=False
Whether to calculate the value function during solution.
CubicBool: bool, default=False
Whether to use cubic spline interpoliation.
AdjustPrb: float or list[float], time varying, default=1.0
Must be between 0 and 1. Probability that the agent can update their risky portfolio share each period. Pass a list of floats to make AdjustPrb time varying.
Simulation Parameters:
----------------------
sim_common_Rrisky: Boolean, default=True
Whether risky returns have a shared/common value across agents. If True, Risky return's can't be time varying.
AgentCount: int, default=10000
Number of agents of this kind that are created during simulations.
T_age: int, default=None
Age after which to automatically kill agents, None to ignore.
T_sim: int, required for simulation
Number of periods to simulate.
track_vars: list[strings]
List of variables that should be tracked when running the simulation.
For this agent, the options are 'Adjust', 'PermShk', 'PlvlAgg', 'Risky', 'TranShk', 'aLvl', 'aNrm', 'bNrm', 'cNrm', 'mNrm', 'pLvl', and 'who_dies'.
Adjust is the array of which agents can adjust
PermShk is the agent's permanent income shock
PlvlAgg is 1
Risky is the agent's risky asset shock
TranShk is the agent's transitory income shock
aLvl is the nominal asset level
aNrm is the normalized assets
bNrm is the normalized resources without this period's labor income
cNrm is the normalized consumption
mNrm is the normalized market resources
pLvl is the permanent income level
who_dies is the array of which agents died
aNrmInitMean: float, default=0.0
Mean of Log initial Normalized Assets.
aNrmInitStd: float, default=1.0
Std of Log initial Normalized Assets.
pLvlInitMean: float, default=0.0
Mean of Log initial permanent income.
pLvlInitStd: float, default=0.0
Std of Log initial permanent income.
PermGroFacAgg: float, default=1.0
Aggregate permanent income growth factor (The portion of PermGroFac attributable to aggregate productivity growth).
PerfMITShk: boolean, default=False
Do Perfect Foresight MIT Shock (Forces Newborns to follow solution path of the agent they replaced if True).
NewbornTransShk: boolean, default=False
Whether Newborns have transitory shock.
Attributes:
-----------
solution: list[Consumer solution object]
Created by the :func:`.solve` method. Finite horizon models create a list with T_cycle+1 elements, for each period in the solution.
Infinite horizon solutions return a list with T_cycle elements for each period in the cycle.
Visit :class:`HARK.ConsumptionSaving.ConsIndShockModel.ConsumerSolution` for more information about the solution.
history: Dict[Array]
Created by running the :func:`.simulate()` method.
Contains the variables in track_vars. Each item in the dictionary is an array with the shape (T_sim,AgentCount).
Visit :class:`HARK.core.AgentType.simulate` for more information.
A consumer type based on IndShockRiskyAssetConsumerType, with portfolio optimization.
The agent is only able to change their risky asset share with a certain probability.
.. math::
\newcommand{\CRRA}{\rho}
\newcommand{\DiePrb}{\mathsf{D}}
\newcommand{\PermGroFac}{\Gamma}
\newcommand{\Rfree}{\mathsf{R}}
\newcommand{\DiscFac}{\beta}
\begin{align*}
v_t(m_t,S_t) &= \max_{c_t,S^{*}_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},S_{t+1}) \right], \\
& \text{s.t.} \\
a_t &= m_t - c_t, \\
a_t &\geq \underline{a}, \\
m_{t+1} &= \mathsf{R}_{t+1}/(\PermGroFac_{t+1} \psi_{t+1}) a_t + \theta_{t+1}, \\
\mathsf{R}_{t+1} &=S_t\phi_{t+1}\mathbf{R}_{t+1}+ (1-S_t)\mathsf{R}_{t+1}, \\
S_{t+1} &= \begin{cases}
S^{*}_t & \text{if } p_t < \wp\\
S_t & \text{if } p_t \geq \wp,
\end{cases}\\
(\psi_{t+1},\theta_{t+1},\phi_{t+1},p_t) &\sim F_{t+1}, \\
\mathbb{E}[\psi]=\mathbb{E}[\theta] &= 1.
\end{align*}
Constructors
------------
IncShkDstn: Constructor
The agent's income shock distributions.
It's default constructor is :func:`HARK.Calibration.Income.IncomeProcesses.construct_lognormal_income_process_unemployment`
aXtraGrid: Constructor
The agent's asset grid.
It's default constructor is :func:`HARK.utilities.make_assets_grid`
ShareGrid: Constructor
The agent's risky asset share grid
It's default constructor is :func:`HARK.ConsumptionSaving.ConsRiskyAssetModel.make_simple_ShareGrid`
RiskyDstn:
The agent's asset shock distribution for risky assets.
It's default constructor is :func:`HARK.Calibration.Assets.AssetProcesses.make_lognormal_RiskyDstn`
Solving Parameters
------------------
cycles: int
0 specifies an infinite horizon model, 1 specifies a finite model.
T_cycle: int
Number of periods in the cycle for this agent type.
CRRA: float, :math:`\rho`
Coefficient of Relative Risk Aversion.
Rfree: float or list[float], time varying, :math:`\mathsf{R}`
Risk Free interest rate. Pass a list of floats to make Rfree time varying.
DiscFac: float, :math:`\beta`
Intertemporal discount factor.
LivPrb: list[float], time varying, :math:`1-\mathsf{D}`
Survival probability after each period.
PermGroFac: list[float], time varying, :math:`\Gamma`
Permanent income growth factor.
BoroCnstArt: float, default=0.0, :math:`\underline{a}`
The minimum Asset/Perminant Income ratio. for this agent, BoroCnstArt must be 0.
vFuncBool: bool
Whether to calculate the value function during solution.
CubicBool: bool
Whether to use cubic spline interpoliation.
AdjustPrb: float or list[float], time varying
Must be between 0 and 1. Probability that the agent can update their risky portfolio share each period. Pass a list of floats to make AdjustPrb time varying.
Simulation Parameters
---------------------
sim_common_Rrisky: Boolean
Whether risky returns have a shared/common value across agents. If True, Risky return's can't be time varying.
AgentCount: int
Number of agents of this kind that are created during simulations.
T_age: int
Age after which to automatically kill agents, None to ignore.
T_sim: int, required for simulation
Number of periods to simulate.
track_vars: list[strings]
List of variables that should be tracked when running the simulation.
For this agent, the options are 'Adjust', 'PermShk', 'Risky', 'TranShk', 'aLvl', 'aNrm', 'bNrm', 'cNrm', 'mNrm', 'pLvl', and 'who_dies'.
Adjust is the array of which agents can adjust
PermShk is the agent's permanent income shock
Risky is the agent's risky asset shock
TranShk is the agent's transitory income shock
aLvl is the nominal asset level
aNrm is the normalized assets
bNrm is the normalized resources without this period's labor income
cNrm is the normalized consumption
mNrm is the normalized market resources
pLvl is the permanent income level
who_dies is the array of which agents died
aNrmInitMean: float
Mean of Log initial Normalized Assets.
aNrmInitStd: float
Std of Log initial Normalized Assets.
pLvlInitMean: float
Mean of Log initial permanent income.
pLvlInitStd: float
Std of Log initial permanent income.
PermGroFacAgg: float
Aggregate permanent income growth factor (The portion of PermGroFac attributable to aggregate productivity growth).
PerfMITShk: boolean
Do Perfect Foresight MIT Shock (Forces Newborns to follow solution path of the agent they replaced if True).
NewbornTransShk: boolean
Whether Newborns have transitory shock.
Attributes
----------
solution: list[Consumer solution object]
Created by the :func:`.solve` method. Finite horizon models create a list with T_cycle+1 elements, for each period in the solution.
Infinite horizon solutions return a list with T_cycle elements for each period in the cycle.
Visit :class:`HARK.ConsumptionSaving.ConsPortfolioModel.PortfolioSolution` for more information about the solution.
history: Dict[Array]
Created by running the :func:`.simulate()` method.
Contains the variables in track_vars. Each item in the dictionary is an array with the shape (T_sim,AgentCount).
Visit :class:`HARK.core.AgentType.simulate` for more information.
"""

IncShkDstn_default = PortfolioConsumerType_IncShkDstn_default
aXtraGrid_default = PortfolioConsumerType_aXtraGrid_default
ShareGrid_default = PortfolioConsumerType_ShareGrid_default
RiskyDstn_default = PortfolioConsumerType_RiskyDstn_default
solving_default = PortfolioConsumerType_solving_default
simulation_default = PortfolioConsumerType_simulation_default

time_inv_ = deepcopy(RiskyAssetConsumerType.time_inv_)
time_inv_ = time_inv_ + ["AdjustPrb", "DiscreteShareBool"]

def __init__(self, verbose=False, quiet=False, **kwds):
params = init_portfolio.copy()
params = PortfolioConsumerType_default.copy()
params.update(kwds)
kwds = params
self.PortfolioBool = True
Expand Down

0 comments on commit 42e3df5

Please sign in to comment.