Journey 1; targeting PhD students - new version to compile all notebooks.

Documentation/conf.py

@@ -39,6 +39,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
     'sphinx.ext.autosummary',
+    'sphinx.ext.imgconverter',
     'numpydoc',
     'nbsphinx',
     'recommonmark',

Documentation/index.rst

@@ -8,12 +8,20 @@ Welcome to HARK's documentation!
    readme
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Notebooks
 
    notebooks/Gentle-Intro-To-HARK
    notebooks/DCT-Copula-Illustration
-
+   notebooks/Journeys_into_HARK	
+
+
+.. toctree::
+   :maxdepth: 3   
+   :caption: Journeys into HARK
+
+   notebooks/Journey_1_PhD
+
 .. toctree::
    :maxdepth: 2
    :caption: Python API

Documentation/notebooks/Gentle-Intro-To-HARK-Buffer-Stock-Model.ipynb

@@ -0,0 +1,223 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# A Gentle Introduction to Buffer Stock Saving \n",
+    "\n",
+    "This notebook explores the behavior of a consumer identical to the perfect foresight consumer described in \"A Gentle Introduction,\" except that now the model incorporates income uncertainty.\n",
+    "\n",
+    "Specifically, our new type of consumer receives two income shocks at the beginning of each period: a completely transitory shock $\\theta_t$ and a completely permanent shock $\\psi_t$.  Moreover, lenders will not let the agent borrow money such that his ratio of end-of-period assets $A_t$ to permanent income $P_t$ is less than $\\underline{a}$. As with the perfect foresight problem, this model can be framed in terms of $\\textit{normalized}$ variables, e.g. $m_t \\equiv M_t/P_t$.  (See [here](http://econ.jhu.edu/people/ccarroll/papers/BufferStockTheory/) for all the theory).\n",
+    "\n",
+    "\\begin{eqnarray*}\n",
+    "v_t(m_t) &=& \\max_{c_t} U(c_t) + \\beta (1 - \\mathsf{D}_{t+1}) \\mathbb{E} [(\\Gamma_{t+1}\\psi_{t+1})^{1-\\rho} v_{t+1}(m_{t+1}) ], \\\\\n",
+    "a_t &=& m_t - c_t, \\\\\n",
+    "a_t &\\geq& \\underline{a}, \\\\\n",
+    "m_{t+1} &=& R/(\\Gamma_{t+1} \\psi_{t+1}) a_t + \\theta_{t+1}, \\\\\n",
+    "(\\psi_t,\\theta_t) \\sim F_{t}, &\\qquad& \\mathbb{E} [F_{\\psi t}] = 1, \\\\\n",
+    "U(c) &=& \\frac{c^{1-\\rho}}{1-\\rho}.\n",
+    "\\end{eqnarray*}\n",
+    "\n",
+    "HARK represents agents with this kind of problem as instances of the class $\\texttt{IndShockConsumerType}$.  To create an $\\texttt{IndShockConsumerType}$, we must specify the same set of parameters as for a $\\texttt{PerfForesightConsumerType}$, as well as an artificial borrowing constraint $\\underline{a}$ and a sequence of income shock distributions $\\{F_t\\}$. It's easy enough to pick a borrowing constraint-- say, zero-- but how would we specify $F_t$?  Can't the joint distribution of permanent and transitory shocks be just about anything?\n",
+    "\n",
+    "$\\textit{Yes}$, and HARK can handle that.  However, the default behavior of $\\texttt{IndShockConsumerType}$ is that the distribution of permanent income shocks is mean one lognormal, and the distribution of transitory shocks is mean one lognormal with a point mass representing unemployment.  The distributions are independent of each other by default, and are approximated with $N$ point equiprobable distributions.\n",
+    "\n",
+    "Let's make an infinite horizon instance of $\\texttt{IndShockConsumerType}$ with the same parameters as our original perfect foresight agent, plus the extra parameters to specify the income shock distribution and the artificial borrowing constraint. As before, we'll make a dictionary:\n",
+    "\n",
+    "\n",
+    "| Param | Description | Code | Value |\n",
+    "| :---: | ---         | ---  | :---: |\n",
+    "| $\\underline{a}$ | Artificial borrowing constraint | $\\texttt{BoroCnstArt}$ | 0.0 |\n",
+    "| $\\sigma_\\psi$ | Underlying stdev of permanent income shocks | $\\texttt{PermShkStd}$ | 0.1 |\n",
+    "| $\\sigma_\\theta$ | Underlying stdev of transitory income shocks | $\\texttt{TranShkStd}$ | 0.1 |\n",
+    "| $N_\\psi$ | Number of discrete permanent income shocks | $\\texttt{PermShkCount}$ | 7 |\n",
+    "| $N_\\theta$ | Number of discrete transitory income shocks | $\\texttt{TranShkCount}$ | 7 |\n",
+    "| $\\mho$ | Unemployment probability | $\\texttt{UnempPrb}$ | 0.05 |\n",
+    "| $\\underline{\\theta}$ | Transitory shock when unemployed | $\\texttt{IncUnemp}$ | 0.3 |"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "code_folding": []
+   },
+   "outputs": [],
+   "source": [
+    "# This cell has just a bit of initial setup. You can click the triangle to the left to expand it.\n",
+    "# Click the \"Run\" button immediately above the notebook in order to execute the contents of any cell\n",
+    "# WARNING: Each cell in the notebook relies upon results generated by previous cells\n",
+    "#   The most common problem beginners have is to execute a cell before all its predecessors\n",
+    "#   If you do this, you can restart the kernel (see the \"Kernel\" menu above) and start over\n",
+    "%matplotlib inline\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "# The first step is to be able to bring things in from different directories\n",
+    "import sys \n",
+    "import os\n",
+    "\n",
+    "sys.path.insert(0, os.path.abspath('../lib'))\n",
+    "\n",
+    "from util import log_progress\n",
+    "\n",
+    "import numpy as np\n",
+    "import HARK \n",
+    "from time import clock\n",
+    "from copy import deepcopy\n",
+    "mystr = lambda number : \"{:.4f}\".format(number)\n",
+    "from HARK.utilities import plotFuncs"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "code_folding": [
+     0,
+     2
+    ]
+   },
+   "outputs": [],
+   "source": [
+    "# This cell defines a parameter dictionary for making an instance of IndShockConsumerType.\n",
+    "\n",
+    "IndShockDictionary = {\n",
+    "    'CRRA': 2.5,          # The dictionary includes our original parameters...\n",
+    "    'Rfree': 1.03,\n",
+    "    'DiscFac': 0.96,\n",
+    "    'LivPrb': [0.98],\n",
+    "    'PermGroFac': [1.01],\n",
+    "    'PermShkStd': [0.1],  # ... and the new parameters for constructing the income process.    \n",
+    "    'PermShkCount': 7,\n",
+    "    'TranShkStd': [0.1],\n",
+    "    'TranShkCount': 7,\n",
+    "    'UnempPrb': 0.05,\n",
+    "    'IncUnemp': 0.3,\n",
+    "    'BoroCnstArt': 0.0,\n",
+    "    'aXtraMin': 0.001,    # aXtra parameters specify how to construct the grid of assets.\n",
+    "    'aXtraMax': 50.,      # Don't worry about these for now\n",
+    "    'aXtraNestFac': 3,\n",
+    "    'aXtraCount': 48,\n",
+    "    'aXtraExtra': [None],\n",
+    "    'vFuncBool': False,   # These booleans indicate whether the value function should be calculated\n",
+    "    'CubicBool': False,   # and whether to use cubic spline interpolation. You can ignore them.\n",
+    "    'aNrmInitMean' : -10.,\n",
+    "    'aNrmInitStd' : 0.0,  # These parameters specify the (log) distribution of normalized assets\n",
+    "    'pLvlInitMean' : 0.0, # and permanent income for agents at \"birth\". They are only relevant in\n",
+    "    'pLvlInitStd' : 0.0,  # simulation and you don't need to worry about them.\n",
+    "    'PermGroFacAgg' : 1.0,\n",
+    "    'T_retire': 0,        # What's this about retirement? ConsIndShock is set up to be able to\n",
+    "    'UnempPrbRet': 0.0,   # handle lifecycle models as well as infinite horizon problems. Swapping\n",
+    "    'IncUnempRet': 0.0,   # out the structure of the income process is easy, but ignore for now.\n",
+    "    'T_age' : None,\n",
+    "    'T_cycle' : 1,\n",
+    "    'cycles' : 0,\n",
+    "    'AgentCount': 10000,\n",
+    "    'tax_rate':0.0,\n",
+    "}\n",
+    "        \n",
+    "# Hey, there's a lot of parameters we didn't tell you about!  Yes, but you don't need to\n",
+    "# think about them for now."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As before, we need to import the relevant subclass of $\\texttt{AgentType}$ into our workspace, then create an instance by passing the dictionary to the class as if the class were a function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from HARK.ConsumptionSaving.ConsIndShockModel import IndShockConsumerType\n",
+    "IndShockExample = IndShockConsumerType(**IndShockDictionary)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can solve our new agent's problem just like before, using the $\\texttt{solve}$ method."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "IndShockExample.solve()\n",
+    "plotFuncs(IndShockExample.solution[0].cFunc,0.,10.)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Changing Constructed Attributes\n",
+    "\n",
+    "In the parameter dictionary above, we chose values for HARK to use when constructing its numeric representation of $F_t$, the joint distribution of permanent and transitory income shocks. When $\\texttt{IndShockExample}$ was created, those parameters ($\\texttt{TranShkStd}$, etc) were used by the $\\textbf{constructor}$ or $\\textbf{initialization}$ method of $\\texttt{IndShockConsumerType}$ to construct an attribute called $\\texttt{IncomeDstn}$.\n",
+    "\n",
+    "Suppose you were interested in changing (say) the amount of permanent income risk.  From the section above, you might think that you could simply change the attribute $\\texttt{TranShkStd}$, solve the model again, and it would work.\n",
+    "\n",
+    "That's $\\textit{almost}$ true-- there's one extra step. $\\texttt{TranShkStd}$ is a primitive input, but it's not the thing you $\\textit{actually}$ want to change. Changing $\\texttt{TranShkStd}$ doesn't actually update the income distribution... unless you tell it to (just like changing an agent's preferences does not change the consumption function that was stored for the old set of parameters -- until you invoke the $\\texttt{solve}$ method again).  In the cell below, we invoke the method $\\texttt{updateIncomeProcess}$ so HARK knows to reconstruct the attribute $\\texttt{IncomeDstn}$."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "OtherExample = deepcopy(IndShockExample)  # Make a copy so we can compare consumption functions\n",
+    "OtherExample.PermShkStd = [0.2]           # Double permanent income risk (note that it's a one element list)\n",
+    "OtherExample.updateIncomeProcess()        # Call the method to reconstruct the representation of F_t\n",
+    "OtherExample.solve()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the cell below, use your blossoming HARK skills to plot the consumption function for $\\texttt{IndShockExample}$ and $\\texttt{OtherExample}$ on the same figure."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "code_folding": []
+   },
+   "outputs": [],
+   "source": [
+    "# Use the line(s) below to plot the consumptions functions against each other\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}