{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Hyperbolic Discounting\n",
    "\n",
    "A major component of Eckstein-Keane-Wolpin models is the intertemporal decision problem that forward-looking agents face when making their choices. In this modeling framework, agents maximize their expected present value of utility over the remaining lifetime. **respy** controls discounting of future payoffs through one or multiple parameters in the `params`. This guide gives a brief overview of the currently available time preferences and how to incorporate them in your model."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We load an example model for illustrative purposes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import respy as rp\n",
    "params, options = rp.get_example_model(\"robinson_crusoe_basic\", with_data=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Standard discounting (`delta`)\n",
    "\n",
    "The standard discount factor in **respy** is called `delta` ($\\delta$) and specified in the `params` object. **respy** expects this parameter to be specified and will raise an error otherwise.\n",
    "\n",
    "The standard discount factor represents time-consistent preferences for $\\delta \\in (0,1]$. However, it can also be set to 0 for a static specification, rendering agents completely myopic."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>category</th>\n",
       "      <th>name</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>delta</th>\n",
       "      <th>delta</th>\n",
       "      <td>0.95</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                value\n",
       "category name        \n",
       "delta    delta   0.95"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.head(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Hyperbolic discounting (`beta`)\n",
    "\n",
    "Aside from standard discounting, **respy** also supports time-inconsistent preferences to be modeled. These types of time preferences follow O’Donoghue and Rabin (1999) and are known as (quasi-)hyperbolic discounting or $\\beta$-$\\delta$ preferences. In this case, in addition to $\\delta$, we also specify a parameter $\\beta \\in (0, 1]$. This parameter implements a present-bias (or impatience) in agents.\n",
    "\n",
    "To implement hyperbolic discounting, add a parameter of category `beta` and name `beta` to the `params` DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>value</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>category</th>\n",
       "      <th>name</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>delta</th>\n",
       "      <th>delta</th>\n",
       "      <td>0.95</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>wage_fishing</th>\n",
       "      <th>exp_fishing</th>\n",
       "      <td>0.30</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>nonpec_fishing</th>\n",
       "      <th>constant</th>\n",
       "      <td>-0.20</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>nonpec_hammock</th>\n",
       "      <th>constant</th>\n",
       "      <td>2.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"3\" valign=\"top\">shocks_sdcorr</th>\n",
       "      <th>sd_fishing</th>\n",
       "      <td>0.50</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sd_hammock</th>\n",
       "      <td>0.50</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>corr_hammock_fishing</th>\n",
       "      <td>0.00</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>beta</th>\n",
       "      <th>beta</th>\n",
       "      <td>0.70</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                     value\n",
       "category       name                       \n",
       "delta          delta                  0.95\n",
       "wage_fishing   exp_fishing            0.30\n",
       "nonpec_fishing constant              -0.20\n",
       "nonpec_hammock constant               2.00\n",
       "shocks_sdcorr  sd_fishing             0.50\n",
       "               sd_hammock             0.50\n",
       "               corr_hammock_fishing   0.00\n",
       "beta           beta                   0.70"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "params.loc[(\"beta\", \"beta\"), \"value\"] = 0.7\n",
    "params"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For an extended example of implementing hyperbolic discounting in one of **respy**'s example models, check out the tutorial linked below."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "<div class=\"d-flex flex-row gs-torefguide\">\n",
    "    <span class=\"badge badge-info\">Tutorials</span>\n",
    "\n",
    "    Find out how to implement hyperbolic discounting in <a\n",
    "    href=\"../tutorials/tutorial_impatient_robinson.html\">Impatient Robinson</a>.\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "- O'Donoghue, T. and and Rabin, M. (1999). [Doing It Now or Later](https://doi.org/10.1257/aer.89.1.103). *American Economic Review*, 89(1): 103-124."
   ]
  }
 ],
 "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.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}