Merge pull request #955 from sbenthall/i952

warning message and autodocs around IncShkDstn fixes

Documentation/CHANGELOG.md

@@ -41,6 +41,7 @@ interpolation for problems with CRRA utility. See [#888](https://github.com/econ
 * Rename IncomeDstn to IncShkDstn
 * AgentType simulate() method now returns history. [#916](https://github.com/econ-ark/HARK/pull/916)
 * Rename DiscreteDistribution.drawDiscrete() to draw()
+* Update documentation and warnings around IncShkDstn [#955](https://github.com/econ-ark/HARK/pull/955)
 
 ### 0.10.8
 

HARK/ConsumptionSaving/ConsAggShockModel.py

@@ -1102,11 +1102,11 @@ def solveConsAggShock(
     ----------
     solution_next : ConsumerSolution
         The solution to the succeeding one period problem.
-    IncShkDstn : [np.array]
-        A list containing five arrays of floats, representing a discrete
+    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, idisyncratic permanent shocks, idiosyncratic transitory
+        and the one immediately following (in solution_next). Order: 
+        idiosyncratic permanent shocks, idiosyncratic transitory
         shocks, aggregate permanent shocks, aggregate transitory shocks.
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of
@@ -1292,11 +1292,11 @@ def solveConsAggShockNEW(solution_next, IncShkDstn, LivPrb, DiscFac, CRRA, PermG
     ----------
     solution_next : ConsumerSolution
         The solution to the succeeding one period problem.
-    IncShkDstn : [np.array]
-        A list containing five arrays of floats, representing a discrete
+    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, idisyncratic permanent shocks, idiosyncratic transitory
+        and the one immediately following (in solution_next). Order: 
+        idiosyncratic permanent shocks, idiosyncratic transitory
         shocks, aggregate permanent shocks, aggregate transitory shocks.
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of
@@ -1438,11 +1438,11 @@ def solveConsAggMarkov(
     ----------
     solution_next : ConsumerSolution
         The solution to the succeeding one period problem.
-    IncShkDstn : [[np.array]]
-        A list of lists, each containing five arrays of floats, representing a
-        discrete approximation to the income process between the period being
-        solved and the one immediately following (in solution_next). Order: event
-        probabilities, idisyncratic permanent shocks, idiosyncratic transitory
+    IncShkDstn : [distribution.Distribution]
+        A list of 
+        discrete approximations to the income process between the period being
+        solved and the one immediately following (in solution_next). Order: 
+        idisyncratic permanent shocks, idiosyncratic transitory
         shocks, aggregate permanent shocks, aggregate transitory shocks.
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of

HARK/ConsumptionSaving/ConsGenIncProcessModel.py

@@ -119,8 +119,8 @@ class ConsGenIncProcessSolver(ConsIndShockSetup):
     ----------
     solution_next : ConsumerSolution
         The solution to next period's one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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.
@@ -199,11 +199,10 @@ def setAndUpdateValues(self, solution_next, IncShkDstn, LivPrb, DiscFac):
         ----------
         solution_next : ConsumerSolution
             The solution to next period's one period problem.
-        IncShkDstn : [np.array]
-            A list containing three arrays of floats, representing a discrete
+        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.
+            and the one immediately following (in solution_next).
         LivPrb : float
             Survival probability; likelihood of being alive at the beginning of
             the succeeding period.

HARK/ConsumptionSaving/ConsIndShockModel.py

@@ -463,11 +463,10 @@ class ConsIndShockSetup(ConsPerfForesightSolver):
     ----------
     solution_next : ConsumerSolution
         The solution to next period's one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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, permanent shocks, transitory shocks.
+        and the one immediately following (in solution_next). 
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of
         the succeeding period.
@@ -1155,11 +1154,10 @@ class ConsKinkedRsolver(ConsIndShockSolver):
     ----------
     solution_next : ConsumerSolution
         The solution to next period's one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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, permanent shocks, transitory shocks.
+        and the one immediately following (in solution_next). 
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of
         the succeeding period.
@@ -2470,16 +2468,15 @@ def constructLognormalIncomeProcessUnemployment(self):
 
         Returns
         -------
-        IncShkDstn :  [[np.array]]
-            A list with T_cycle elements, each of which is a list of three arrays
-            representing a discrete approximation to the income process in a period.
-            Order: probabilities, permanent shocks, transitory shocks.
-        PermShkDstn : [[np.array]]
-            A list with T_cycle elements, each of which is a list of two arrays
-            representing a discrete approximation to the permanent income shocks.
-        TranShkDstn : [[np.array]]
-            A list with T_cycle elements, each of which is a list of two arrays
-            representing a discrete approximation to the transitory income shocks.
+        IncShkDstn :  [distribution.Distribution]
+            A list with T_cycle elements, each of which is a 
+            discrete approximation to the income process in a period.
+        PermShkDstn : [[distribution.Distributiony]]
+            A list with T_cycle elements, each of which
+            a discrete approximation to the permanent income shocks.
+        TranShkDstn : [[distribution.Distribution]]
+            A list with T_cycle elements, each of which 
+            a discrete approximation to the transitory income shocks.
         """
         # Unpack the parameters from the input
         PermShkStd = self.PermShkStd
@@ -2735,7 +2732,7 @@ def applyFlatIncomeTax(
 
     Parameters
     ----------
-    IncShkDstn : [income distributions]
+    IncShkDstn : [distribution.Distribution]
         The discrete approximation to the income distribution in each time period.
     tax_rate : float
         A flat income tax rate to be applied to all employed income.
@@ -2748,7 +2745,7 @@ def applyFlatIncomeTax(
 
     Returns
     -------
-    IncShkDstn_new : [income distributions]
+    IncShkDstn_new : [distribution.Distribution]
         The updated income distributions, after applying the tax.
     """
     unemployed_indices = (

HARK/ConsumptionSaving/ConsMarkovModel.py

@@ -86,12 +86,11 @@ def __init__(
         ----------
         solution_next : ConsumerSolution
             The solution to next period's one period problem.
-        IncShkDstn_list : [[np.array]]
+        IncShkDstn_list : [distribution.Distribution]
             A length N list of income distributions in each succeeding Markov
-            state.  Each income distribution contains three arrays of floats,
-            representing a discrete approximation to the income process at the
-            beginning of the succeeding period. Order: event probabilities,
-            permanent shocks, transitory shocks.
+            state.  Each income distribution is a
+            discrete approximation to the income process at the
+            beginning of the succeeding period.
         LivPrb : np.array
             Survival probability; likelihood of being alive at the beginning of
             the succeeding period for each Markov state.
@@ -761,12 +760,11 @@ def _solveConsMarkov(
     ----------
     solution_next : ConsumerSolution
         The solution to next period's one period problem.
-    IncShkDstn_list : [[np.array]]
+    IncShkDstn_list : [distribution.Distribution]
         A length N list of income distributions in each succeeding Markov
-        state.  Each income distribution contains three arrays of floats,
-        representing a discrete approximation to the income process at the
-        beginning of the succeeding period. Order: event probabilities,
-        permanent shocks, transitory shocks.
+        state.  Each income distribution is
+        a discrete approximation to the income process at the
+        beginning of the succeeding period.
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of
         the succeeding period.
@@ -906,7 +904,13 @@ def checkMarkovInputs(self):
         # conditional on a particular Markov state.
         # TODO: should this be a numpy array too?
         for IncShkDstn_t in self.IncShkDstn:
-            if not isinstance(IncShkDstn_t, list) or len(IncShkDstn_t) != StateCount:
+            if not isinstance(IncShkDstn_t, list):
+                raise ValueError(
+                    "self.IncShkDstn is time varying and so must be a list"
+                    + "of lists of Distributions, one per Markov State. Found "
+                    + f"{self.IncShkDstn} instead"
+                )
+            elif len(IncShkDstn_t) != StateCount:
                 raise ValueError(
                     "List in IncShkDstn is not the right length, it should be length equal to number of states"
                 )

HARK/ConsumptionSaving/ConsMedModel.py

@@ -885,14 +885,13 @@ class ConsMedShockSolver(ConsGenIncProcessSolver):
     ----------
     solution_next : ConsumerSolution
         The solution to next period's one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
-        approximation to the income process between the period being solved
-        and the one immediately following (in solution_next). Order: event
-        probabilities, permanent shocks, transitory shocks.
-    MedShkDstn : [np.array]
+    IncShkDstn : distribution.Distribution
+        A discrete
+        approximations to the income process between the period being solved
+        and the one immediately following (in solution_next).
+    MedShkDstn : distribution.Distribution
         Discrete distribution of the multiplicative utility shifter for med-
-        ical care. Order: probabilities, preference shocks.
+        ical care. 
     LivPrb : float
         Survival probability; likelihood of being alive at the beginning of
         the succeeding period.
@@ -977,11 +976,10 @@ def setAndUpdateValues(self, solution_next, IncShkDstn, LivPrb, DiscFac):
         ----------
         solution_next : ConsumerSolution
             The solution to next period's one period problem.
-        IncShkDstn : [np.array]
-            A list containing three arrays of floats, representing a discrete
+        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, permanent shocks, transitory shocks.
+            and the one immediately following (in solution_next).
         LivPrb : float
             Survival probability; likelihood of being alive at the beginning of
             the succeeding period.

HARK/ConsumptionSaving/ConsPortfolioModel.py

@@ -536,8 +536,8 @@ def solveConsPortfolio(
         transitory income shocks, and risky returns.  This is only used if the
         input IndepDstnBool is False, indicating that income and return distributions
         can't be assumed to be independent.
-    IncShkDstn : [np.array]
-        List with three arrays: discrete probabilities, permanent income shocks,
+    IncShkDstn : distribution.Distribution
+        Discrete distribution of permanent income shocks
         and transitory income shocks.  This is only used if the input IndepDsntBool
         is True, indicating that income and return distributions are independent.
     RiskyDstn : [np.array]

HARK/ConsumptionSaving/ConsPrefShockModel.py

@@ -301,8 +301,8 @@ class ConsPrefShockSolver(ConsIndShockSolver):
     ----------
     solution_next : ConsumerSolution
         The solution to the succeeding one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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, permanent shocks, transitory shocks.
@@ -542,8 +542,8 @@ def solveConsPrefShock(
     ----------
     solution_next : ConsumerSolution
         The solution to the succeeding one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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, permanent shocks, transitory shocks.
@@ -620,8 +620,8 @@ class ConsKinkyPrefSolver(ConsPrefShockSolver, ConsKinkedRsolver):
     ----------
     solution_next : ConsumerSolution
         The solution to the succeeding one period problem.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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, permanent shocks, transitory shocks.

HARK/ConsumptionSaving/ConsRepAgentModel.py

@@ -35,11 +35,11 @@ def solveConsRepAgent(
         Intertemporal discount factor for future utility.
     CRRA : float
         Coefficient of relative risk aversion.
-    IncShkDstn : [np.array]
-        A list containing three arrays of floats, representing a discrete
+    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, permanent shocks, transitory shocks.
+        and the one immediately following (in solution_next). Order: 
+        permanent shocks, transitory shocks.
     CapShare : float
         Capital's share of income in Cobb-Douglas production function.
     DeprFac : float
@@ -135,9 +135,9 @@ def solveConsRepAgentMarkov(
         Intertemporal discount factor for future utility.
     CRRA : float
         Coefficient of relative risk aversion.
-    IncShkDstn : [[np.array]]
-        A list of lists containing three arrays of floats, representing a discrete
-        approximation to the income process between the period being solved
+    IncShkDstn : [distribution.Distribution]
+        A list of discrete
+        approximations to the income process between the period being solved
         and the one immediately following (in solution_next). Order: event
         probabilities, permanent shocks, transitory shocks.
     CapShare : float