From 42e3df5a3e2ba9e8e96ccf82a8bb7d26b0fa584b Mon Sep 17 00:00:00 2001 From: dominicWC <135868541+DominicWC@users.noreply.github.com> Date: Tue, 20 Aug 2024 11:04:43 -0400 Subject: [PATCH] Adds ConsPortfolioModel's updated documentation --- HARK/ConsumptionSaving/ConsPortfolioModel.py | 337 +++++++++---------- 1 file changed, 158 insertions(+), 179 deletions(-) diff --git a/HARK/ConsumptionSaving/ConsPortfolioModel.py b/HARK/ConsumptionSaving/ConsPortfolioModel.py index 36f4ae40d..5322676cd 100644 --- a/HARK/ConsumptionSaving/ConsPortfolioModel.py +++ b/HARK/ConsumptionSaving/ConsPortfolioModel.py @@ -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, @@ -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 @@ -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 @@ -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 @@ -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 @@ -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