Merge pull request #683 from rickecon/ubi

Big documentation update

docs/book/OGUSA_references.bib

@@ -238,22 +238,24 @@ @TECHREPORT{DeBackerRamnath:2017
   Year = {2017},
 }
 
-@TECHREPORT{DeBackerEtAl:2017b,
+@TECHREPORT{DeBackerEtAl:2017,
   AUTHOR = {Jason DeBacker and Richard W. Evans and Evan Magnusson and Kerk L. Phillips and Shanthi Ramnath and Isaac Swift},
   TITLE = {The Distributional Effects of Redistributional Tax Policy},
   INSTITUTION = {Open Source Macroeconomics Laboratory},
-  YEAR = {2017b},
+  YEAR = {2017},
   type = {mimeo},
   month = {January},
 }
 
-@TECHREPORT{DeBackerEtAl:2017,
+@ARTICLE{DeBackerEtAl:2019,
   AUTHOR = {Jason DeBacker and Richard W. Evans and Kerk L. Phillips},
-  TITLE = {Integrating Microsimulation Models of Tax Policy into a DGE Macroeconomic Model: A Canonical Example},
-  INSTITUTION = {Open Source Macroeconomics Laboratory},
-  YEAR = {2017},
-  type = {mimeo},
+  TITLE = {Integrating Microsimulation Models of Tax Policy into a DGE Macroeconomic Model},
+  JOURNAL = {Public Finance Review},
+  YEAR = {2019},
+  volume = {47},
+  number = {2},
   month = {March},
+  pages = {207-275},
 }
 
 @ARTICLE{DeNardi:2004,
@@ -673,7 +675,7 @@ @ARTICLE{Suzumura:1983
   Author = {Kotaro Suzumura},
   Journal = {Hitotsubashi Journal of Economics},
   Pages = {137-141},
-  Title = {Perron-Frobenius Theorm on Non-Negative Square Matrices: An Elementary Proof},
+  Title = {Perron-Frobenius Theorem on Non-Negative Square Matrices: An Elementary Proof},
   Volume = {24},
   Year = {1983},
 }

docs/book/_config.yml

@@ -2,7 +2,7 @@
 # Book settings
 title                    : OG-USA
 author                   : Jason DeBacker and Richard W. Evans
-copyright                : '2020'
+copyright                : '2021'
 logo                     : '..//OG-USA_logo.png'
 
 ####################################################
@@ -57,3 +57,5 @@ latex:
   latex_engine           : 'xelatex'
   latex_documents:
     targetname           : book.tex
+bibtex_bibfiles:
+   - OGUSA_references.bib

docs/book/_toc.yml

@@ -35,9 +35,9 @@
   - file: content/theory/firms
   - file: content/theory/government
   - file: content/theory/market_clearing
+  - file: content/theory/open_economy
   - file: content/theory/stationarization
   - file: content/theory/equilibrium
-  - file: content/theory/open_economy
 
 - part: Calibration
   chapters:
@@ -47,6 +47,8 @@
   - file: content/calibration/earnings
   - file: content/calibration/tax_functions
   - file: content/calibration/bequests
+  - file: content/calibration/UBI
+  - file: content/calibration/matching_lwi
 
 
 - part: Appendix

docs/book/content/api/public_api.rst

@@ -1,16 +1,13 @@
 API
 =========================
-The source code for OG-USA is located in the
-OG-USA/ogusa directory tree.
+The source code for `OG-USA` is located in the OG-USA/ogusa directory tree.
 
-Here we provide a high-level view of the API of the OG-USA model, with
-links to the source code.  This high-level view is
-organized around the modules that make up the OG-USA model.  Below is a list
-of these modules (in alphabetical order) with
-documentation about how to call each class method and function.
+Here we provide a high-level view of the API of the `OG-USA` model, with links
+to the source code. This high-level view is organized around the modules that
+make up the `OG-USA` model. Below is a list of these modules (in alphabetical
+order) with documentation about how to call each class method and function.
 There is also a link to the source code for each documented member.
 
-
 .. toctree::
    :maxdepth: 1
 

docs/book/content/calibration/UBI.md

@@ -0,0 +1,63 @@
+(Chap_UBI)=
+# Universal Basic Income (UBI)
+
+[TODO: This section is far along but needs to be updated.]
+
+We have included the modeling of a universal basic income (UBI) policy directly in the theory and code for `OG-USA`. We calculate the time series of a UBI matrix $ubi_{j,s,t}$ representing the UBI transfer to every household with head of household age $s$, lifetime income group $j$, in period $t$. We calculate the time series of this matrix from five parameters and some household composition data that we impose upon the existing demographics of `OG-USA`.
+
+
+(SecUBIcalc)=
+## Calculating UBI
+
+  We calculate the time series of UBI household transfers in model units $ubi_{j,s,t)}$ and the time series of total UBI expenditures in model units $UBI_t$ from five parameters described in the `OG-USA` API (`ubi_growthadj`, `ubi_nom_017`, `ubi_nom_1820`, `ubi_nom_2164`, `ubi_nom_65p`, and `ubi_nom_max`) interfaced with the `OG-USA` demographic dynamics over lifetime income groups $j$ and ages $s$, and multiplied by household composition matrices from the [OG-USA-calibration](https://github.com/PSLmodels/OG-USA-Calibration) repository.
+
+  From the [OG-USA-calibration](https://github.com/PSLmodels/OG-USA-Calibration) repository, we have four $S\times J$ matrices `ubi_num_017_mat`$_{j,s}$, `ubi_num_1820_mat`$_{j,s}$, `ubi_num_2164_mat`$_{j,s}$, and `ubi_num_65p_mat`$_{j,s}$ representing the number of children under age 0-17, number of adults ages 18-20, the number of adults between ages 21 and 64, and the number of seniors age 65 and over, respectively, by lifetime ability group $j$ and age $s$ of head of household. Because our demographic age data match up well with head-of-household data from other datasets, we do not have to adjust the values in these matrices.[^HOH_age_dist_note]
+
+  Now we can solve for the dollar-valued (as opposed to model-unit-valued) UBI transfer to each household in the first period $ubi^{\$}_{j,s,t=0}$ in the following way. Let the parameter `ubi_nom_017` be the dollar value of the UBI transfer to each household per dependent child age 17 and under. Let the parameter `ubi_nom_1820` be the dollar value of the UBI transfer to each household per dependent child between the ages of 18 and 20. Let `ubi_nom_2164` and `ubi_nom_65p` be the dollar value of UBI transfer to each household per adult between ages 21 and 64 and per senior 65 and over, respectively. And let `ubi_nom_max` be the maximum UBI benefit per household.
+
+  ```{math}
+  :label: EqUBIubi_dol_jst0
+    \begin{split}
+      ubi^{\$}_{j,s,t=0} = \min\Bigl(&\texttt{ubi_nom_max}, \\
+      &\texttt{ubi_nom_017} * \texttt{ubi_num_017_mat}_{j,s} + \\
+      &\texttt{ubi_nom_1820} * \texttt{ubi_num_1820_mat}_{j,s} + \\
+      &\texttt{ubi_nom_2164} * \texttt{ubi_num_2164_mat}_{j,s} + \\
+      &\texttt{ubi_nom_65p} * \texttt{ubi_num_65p_mat}_{j,s}\Bigr) \quad\forall j,s
+    \end{split}
+  ```
+
+  The rest of the time periods of the household UBI transfer and the respective steady-states are determined by whether the UBI is growth adjusted or not as given in the `ubi_growthadj` Boolean parameter. The following two sections cover these two cases.
+
+
+(SecUBI_NonGrowthAdj)=
+## UBI specification not adjusted for economic growth
+
+  A non-growth adjusted UBI (`ubi_growthadj = False`) is one in which the initial nonstationary dollar-valued $t=0$ UBI matrix $ubi^{\$}_{j,s,t=0}$ does not grow, while the economy's long-run growth rate is $g_y$ for the most common parameterization where the long-run growth rate is positive $g_y>0$.
+
+  ```{math}
+  :label: EqUBIubi_dol_NonGrwAdj_jst
+    ubi^{\$}_{j,s,t} = ubi^{\$}_{j,s,t=0} \quad\forall j,s,t
+  ```
+
+  As described in Chapter {ref}`Chap_Stnrz`, the stationarized UBI transfer to each household $\hat{ubi}_{j,s,t}$ is the nonstationary transfer divided by the growth rate since the initial period. When the long-run economic growth rate is positive $g_y>0$ and the UBI specification is not growth-adjusted the steady-state stationary UBI household transfer is zero $\overline{ubi}_{j,s}=0$ for all lifetime income groups $j$ and ages $s$ as time periods $t$ go to infinity. However, to simplify, we assume in this case that the stationarized steady-state UBI transfer matrix to households is the stationarized value of that matrix in period $T$.
+
+  ```{math}
+  :label: EqUBIubi_mod_NonGrwAdj_SS
+    \overline{ubi}_{j,s} = ubi_{j,s,t=T} \quad\forall j,s
+  ```
+
+  Note that in non-growth-adjusted case, if $g_y<0$, then the stationary value of $\hat{ubi}_{j,s,t}$ is going to infinity as $t$ goes to infinity. Therefore, a UBI specification must be growth adjusted for any assumed negative long run growth $g_y<0$.[^GrowthAdj_note]
+
+
+(SecUBI_GrowthAdj)=
+## UBI specification adjusted for economic growth
+
+  Put description of growth-adjusted specification here.
+
+
+(SecUBIfootnotes)=
+## Footnotes
+
+[^HOH_age_dist_note]: DeBacker and Evans compared the `OG-USA` age demographics $\hat{\omega}_{s,t}$ with the respective age demographics in Tax Policy Center's microsimulation model and in [Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator)'s microsimulation model. The latter two microsimulation models' age demographics are based on head of household tax filer age distributions, whereas `OG-USA`'s demographics are based on the population age distribution.
+
+[^GrowthAdj_note]: We impose this requirement of `ubi_growthadj = False` when `g_y_annual < 0` in the [`default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/default_parameters.json) "validators" specification of the parameter.

docs/book/content/calibration/bequests.md

@@ -1,6 +1,8 @@
 (Chap_Beq)=
 # Bequest Process Calibration
 
+[TODO: This chapter needs to be finished.]
+
 This chapter describes how we calibrate the distribution of total bequests $BQ_t$ to each living household of age $s$ and lifetime income group $j$. The matrix that governs this distribution $\zeta_{j,s}$ is seen in the household budget constraint {ref}`EqHHBC`.
 
 A large number of papers study the effects of different bequest motives and specifications on the distribution of wealth, though there is no consensus regarding the true bequest transmission process.  See {cite}`DeNardiYang:2014`, {cite}`DeNardi:2004`, {cite}`Nishiyama:2002`, {cite}`Laitner:2001`, {cite}`GokhaleEtAl:2000`, {cite}`GaleScholz:1994`, {cite}`Hurd:1989`, {cite}`VentiWise:1988`, {cite}`KotlikoffSummers:1981`, and {cite}`Wolff:2015`.

docs/book/content/calibration/demographics.md

@@ -16,7 +16,7 @@ kernelspec:
 (Chap_Demog)=
 # Demographics
 
-We start the `OG-USA` section on modeling the household with a description of the demographics of the model. {cite}`Nishiyama:2015` and {cite}`DeBackerEtAl:2017` have recently shown that demographic dynamics are likely the biggest influence on macroeconomic time series, exhibiting more influence than fiscal variables or household preference parameters.
+We start the `OG-USA` section on modeling the household with a description of the demographics of the model. {cite}`Nishiyama:2015` and {cite}`DeBackerEtAl:2019` have recently shown that demographic dynamics are likely the biggest influence on macroeconomic time series, exhibiting more influence than fiscal variables or household preference parameters.
 
 In this chapter, we characterize the equations and parameters that govern the transition dynamics of the population distribution by age. In `OG-USA`, we take the approach of taking mortality rates and fertility rates from outside estimates. But we estimate our immigration rates as residuals using the mortality rates, fertility rates, and at least two consecutive periods of population distribution data. This approach makes sense if one modeling a country in which in one is not confident in the immigration rate data. If the country has good immigration data, then the immigration residual approach we describe below can be skipped.
 

docs/book/content/calibration/earnings.md

@@ -27,7 +27,7 @@ Differences among workers' productivity in terms of ability is one of the key di
 
 In this specification, $w_t$ is an equilibrium wage representing a portion of labor income that is common to all workers. Individual quantity of labor supply is $n_{j,s,t}$, and $e_{j,s}$ represents a labor productivity factor that augments or diminishes the productivity of a worker's labor supply relative to average productivity.
 
-We calibrate deterministic ability paths such that each lifetime income group has a different life-cycle profile of earnings. The distribution on income and wealth are often focal components of macroeconomic models. As such, we use a calibration of deterministic lifetime ability paths from {cite}`DeBackerEtAl:2017b` that can represent U.S. earners in the top 1\% of the distribution of lifetime income. {cite}`PikettySaez:2003` show that income and wealth attributable to these households has shown the greatest growth in recent decades. The data come from the U.S. Internal Revenue Services's (IRS) Statistics of Income program (SOI) Continuous Work History Sample (CWHS). {cite}`DeBackerEtAl:2017b` match the SOI data with Social Security Administration (SSA) data on age and Current Population Survey (CPS) data on hours in order to generate a non-top-coded measure of hourly wage.
+We calibrate deterministic ability paths such that each lifetime income group has a different life-cycle profile of earnings. The distribution on income and wealth are often focal components of macroeconomic models. As such, we use a calibration of deterministic lifetime ability paths from {cite}`DeBackerEtAl:2017` that can represent U.S. earners in the top 1\% of the distribution of lifetime income. {cite}`PikettySaez:2003` show that income and wealth attributable to these households has shown the greatest growth in recent decades. The data come from the U.S. Internal Revenue Services's (IRS) Statistics of Income program (SOI) Continuous Work History Sample (CWHS). {cite}`DeBackerEtAl:2017` match the SOI data with Social Security Administration (SSA) data on age and Current Population Survey (CPS) data on hours in order to generate a non-top-coded measure of hourly wage.
 
 ```{figure} ../theory/images/ability_log_2D.png
 ---
@@ -57,7 +57,7 @@ Exogenous life cycle income ability paths $\log(e_{j,s})$ with $S=80$ and $J=7$
 -->
 
 
-Figure {numref}`FigLogAbil` shows a calibration for $J=7$ deterministic lifetime ability paths $e_{j,s}$ corresponding to labor income percentiles $\boldsymbol{\lambda}=[0.25, 0.25, 0.20, 0.10, 0.10, 0.09, 0.01]$. Because there are few individuals above age 80 in the data, {cite}`DeBackerEtAl:2017b` extrapolate these estimates for model ages 80-100 using an arctan function.
+Figure {numref}`FigLogAbil` shows a calibration for $J=7$ deterministic lifetime ability paths $e_{j,s}$ corresponding to labor income percentiles $\boldsymbol{\lambda}=[0.25, 0.25, 0.20, 0.10, 0.10, 0.09, 0.01]$. Because there are few individuals above age 80 in the data, {cite}`DeBackerEtAl:2017` extrapolate these estimates for model ages 80-100 using an arctan function.
 
 We calibrate the model such that each lifetime income group has a different life-cycle profile of earnings. Since the distribution on income and wealth are key aspects of our model, we calibrate these processes so that we can represent earners in the top 1 percent of the distribution of lifetime income. It is income and wealth attributable to these households that has shown the greatest growth in recent decades (see, for example, {cite}`PikettySaez:2003`). In order to have observations on the earnings of those at very top of the distribution that are not subject to top-coding we use data from the Internal Revenue Services's (IRS) Statistics of Income program (SOI).
 
@@ -494,7 +494,7 @@ Because we do not have panel data that allow us to observe such top percentile g
   - 1.000
 * - Top 1-0.5%
   - $524,677
-  - 0.459 
+  - 0.459
 * - Top 0.5-0.1%
   - $968,991
   - 0.847
@@ -513,4 +513,4 @@ Because we do not have panel data that allow us to observe such top percentile g
 
 [^threshold_note]: This threshold is equivalent to \$50 million of wage income in one year at full time (40 hours per week) of work.
 
-[^PS_note]: These data are available from the website of Emmanuel Saez: [https://eml.berkeley.edu/~saez/](https://eml.berkeley.edu/~saez/).  We use numbers from Table0, Panel B, "Income excluding realized capital gains."
+[^PS_note]: These data are available from the website of Emmanuel Saez: [https://eml.berkeley.edu/~saez/](https://eml.berkeley.edu/~saez/).  We use numbers from Table0, Panel B, "Income excluding realized capital gains."

docs/book/content/calibration/exogenous_parameters.md

@@ -15,6 +15,7 @@ kernelspec:
 (Chap_Exog)=
 # Exogenous Parameters
 
+  [TODO: This chapter needs heavy updating. Would be nice to do something similar to API chapter. But it is also nice to have references and descriptions as in the table below.]
 
   In this chapter, list the exogenous inputs to the model, options, and where the values come from (weak calibration vs. strong calibration). Point to the respective chapters for some of the inputs. Mention the code in [`default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/default_parameters.json) and [`parameters.py`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/parameters.py).
 

docs/book/content/calibration/matching_lwi.md

@@ -0,0 +1,4 @@
+(Chap_matchingLWI)=
+# Matching Labor, Wealth, and Income Moments
+
+[TODO: We should include our calibration notes here for how we calibrate `OG-USA` to match the distribution of labor supply by age in the data, how we match wealth share moments, and how we match income share moments.]