diff --git a/.gitignore b/.gitignore index 062ddd93..c29b56e0 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,8 @@ *.pyc +MANIFEST +build/* +dist/* +*.cache/ .coverage .coveragerc htmlcov/* @@ -31,4 +35,11 @@ htmlcov/* */OUTPUT/* envs/ *.egg-info/ -dask-worker-space/ +*dask-worker-space* +.ipynb_checkpoints* +*/__pycache__/* +docs/book/_build/* +docs/build* +examples/OG-USA_example_plots/* +examples/ogusa_example_output.csv +examples/OG-USA-Example/* diff --git a/PSL_catalog.json b/PSL_catalog.json index e558fff4..e2f9c7d2 100644 --- a/PSL_catalog.json +++ b/PSL_catalog.json @@ -135,7 +135,7 @@ "core_maintainers": { "start_header": null, "end_header": null, - "data": "", + "data": "", "source": null, "type": "html" }, diff --git a/README.md b/README.md index 1be3f741..10874dd7 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![Codecov](https://codecov.io/gh/PSLmodels/OG-USA/branch/master/graph/badge.svg)](https://codecov.io/gh/PSLmodels/OG-USA) # OG-USA -OG-USA is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy for the United States. OG-USA is build on the [OG-Core](https://github.com/PSLmodels/OG-Core) framework. The model output includes changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. Regularly updated documentation of the model theory--its output, and solution method--and the Python API is available at [https://pslmodels.github.io/OG-Core](https://pslmodels.github.io/OG-Core) and documentation of the specific United States calibration of the model is available at [https://pslmodels.github.io/OG-USA](https://pslmodels.github.io/OG-USA). +OG-USA is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy for the United States. OG-USA is built on the [OG-Core](https://github.com/PSLmodels/OG-Core) framework. The model output includes changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. Regularly updated documentation of the model theory--its output, and solution method--and the Python API is available at [https://pslmodels.github.io/OG-Core](https://pslmodels.github.io/OG-Core) and documentation of the specific United States calibration of the model is available at [https://pslmodels.github.io/OG-USA](https://pslmodels.github.io/OG-USA). @@ -11,7 +11,7 @@ OG-USA is an overlapping-generations (OG) model that allows for dynamic general * Install the [Anaconda distribution](https://www.anaconda.com/distribution/) of Python * Clone this repository to a directory on your computer -* From the terminal (or Conda command prompt), navigate to the directory to which you cloned this repository and run `conda env create -f environment.yml` +* From the terminal (or Conda command prompt), navigate to the directory to which you cloned this repository and run `conda env create -f environment.yml`. The process of creating the `ogusa-dev` conda environment can take more than 20 minutes. The pip install of the `OG-Core` dependency from GitHub takes most of the time. * Then, `conda activate ogusa-dev` * Then install by `pip install -e .` * Navigate to `./examples` @@ -24,13 +24,13 @@ OG-USA is an overlapping-generations (OG) model that allows for dynamic general * This is a summary of the percentage changes in macro variables over the first ten years and in the steady-state. * `./examples/OG-USA-Example/OUTPUT_BASELINE/model_params.pkl` * Model parameters used in the baseline run - * See `ogcore.execute.py` for items in the dictionary object in this pickle file + * See [`ogcore.execute.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/execute.py) for items in the dictionary object in this pickle file * `./examples/OG-USA-Example/OUTPUT_BASELINE/SS/SS_vars.pkl` * Outputs from the model steady state solution under the baseline policy - * See `ogcore.SS.py` for what is in the dictionary object in this pickle file + * See [`ogcore.SS.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/SS.py) for what is in the dictionary object in this pickle file * `./examples/OG-USA-Example/OUTPUT_BASELINE/TPI/TPI_vars.pkl` * Outputs from the model timepath solution under the baseline policy - * See `ogcore.TPI.py` for what is in the dictionary object in this pickle file + * See [`ogcore.TPI.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/TPI.py) for what is in the dictionary object in this pickle file * An analogous set of files in the `./examples/OUTPUT_REFORM` directory, which represent objects from the simulation of the reform policy Note that, depending on your machine, a full model run (solving for the full time path equilibrium for the baseline and reform policies) can take more than two hours of compute time. @@ -47,9 +47,16 @@ c = Calibration(p) updated_params = c.get_dict() p.update_specifications({'initial_debt_ratio': updated_params['initial_debt_ratio']}) ``` -# Disclaimer +## Disclaimer The organization of this repository will be changing rapidly, but the `OG-USA/examples/run_og_usa.py` script will be kept up to date to run with the master branch of this repo. -# Citing OG-USA +## Core Maintainers + +The core maintainers of the OG-Core repository are: + +* [Jason DeBacker](https://www.jasondebacker.com/) (GitHub handle: [jdebacker](https://github.com/jdebacker)), Associate Professor, Department of Economics, Darla Moore School of Business, University of South Carolina; President, PSL Foundation; Vice President of Research and Co-founder, Open Research Group, Inc. +* [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle: [rickecon](https://github.com/rickecon)), Advisory Board Visiting Fellow, Center for Public Finance, Baker Institute for Public Policy at Rice University; President, Open Research Group, Inc.; Director, Open Source Economics Laboratory + +## Citing OG-USA OG-USA (Version 0.0.0)[Source code], https://github.com/PSLmodels/OG-USA diff --git a/docs/book/_config.yml b/docs/book/_config.yml index 82eb08bf..93bb28fd 100644 --- a/docs/book/_config.yml +++ b/docs/book/_config.yml @@ -1,6 +1,6 @@ #################################################### # Book settings -title : OG-USA-Calibration +title : OG-USA author : Jason DeBacker and Richard W. Evans copyright : '2021' logo : '..//OG-USA_logo.png' @@ -40,7 +40,7 @@ launch_buttons: #################################################### # Information about where the book exists on the web repository: - url : https://github.com/PSLmodels/OG-USA-Calibration + url : https://github.com/PSLmodels/OG-USA path_to_book : 'book' ####################################################################################### @@ -58,4 +58,5 @@ latex: latex_documents: targetname : book.tex bibtex_bibfiles: - - OGUSA_references.bib + - OGUSA_references.bib + - citations.bib diff --git a/docs/book/_toc.yml b/docs/book/_toc.yml index 7b3b56ca..b5e5c57c 100644 --- a/docs/book/_toc.yml +++ b/docs/book/_toc.yml @@ -1,23 +1,12 @@ format: jb-book root: content/intro/intro parts: -- caption: Contributing to OG-USA-Calibration +- caption: Contributing to OG-USA chapters: - file: content/contributing/contributor_guide -- caption: OG-USA-Calibration API +- caption: OG-USA API chapters: - file: content/api/public_api - sections: - - file: content/api/bequest_transmission - - file: content/api/calibrate - - file: content/api/demographics - - file: content/api/deterministic_profiles - - file: content/api/estimate_beta_j - - file: content/api/get_micro_data - - file: content/api/income - - file: content/api/macro_params - - file: content/api/transfer_distribution - - file: content/api/txfunc - caption: Calibration chapters: - file: content/calibration/exogenous_parameters @@ -30,7 +19,7 @@ parts: - file: content/calibration/matching_lwi - caption: References chapters: - - file: content/calibration/references -- caption: Citations of OG-USA-Calibration + - file: content/OGUSA_references +- caption: Citations of OG-USA chapters: - file: content/citations diff --git a/docs/book/citations.bib b/docs/book/citations.bib new file mode 100644 index 00000000..4030e566 --- /dev/null +++ b/docs/book/citations.bib @@ -0,0 +1,207 @@ +@TECHREPORT{DeBackerEtAl:2017b, + 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}, + type = {mimeo}, + month = {January}, +} + +@Article{DEP:2019, + author={Jason DeBacker and Richard W. Evans and Kerk L. Phillips}, + title={{Integrating Microsimulation Models of Tax Policy into a DGE Macroeconomic Model}}, + journal={Public Finance Review}, + year=2019, + volume={47}, + number={2}, + pages={207-275}, + month={March}, + keywords={microsimulation; effective tax rates; marginal tax rates; dynamic general equilibrium; dynamic scori}, + doi={}, + abstract={This article proposes a method for integrating individual effective tax rates and marginal tax rates computed from a microsimulation (partial equilibrium) model of tax policy with a dynamic general equilibrium model of tax policy that can provide macroeconomic analysis or dynamic scores of tax reforms. Our approach captures the rich heterogeneity, realistic demographics, and tax-code detail of the microsimulation model and allows this detail to inform a general equilibrium model with a relatively high degree of heterogeneity. In addition, we propose a functional form in which tax rates depend jointly on the levels of both capital income and labor income.}, + url={https://ideas.repec.org/a/sae/pubfin/v47y2019i2p207-275.html} +} + +@TECHREPORT{Pomerleau2020b, + AUTHOR = {Kyle Pomerleau}, + TITLE = {An analysis of Joe Biden’s tax proposals, October 2020 update}, + INSTITUTION = {American Enterprise Institute}, + YEAR = {2020}, + type = {AEI Report}, + month = {October}, + url = {https://www.aei.org/research-products/report/an-analysis-of-joe-bidens-tax-proposals-october-2020-update/} +} + +@TECHREPORT{DEP2020, + AUTHOR = {Jason DeBacker and Richard Evans and Kyle Pomerleau}, + TITLE = {An analysis of Joe Biden’s tax proposals}, + INSTITUTION = {American Enterprise Institute}, + YEAR = {2020}, + type = {AEI Report}, + month = {June}, + url = {https://www.aei.org/research-products/report/an-analysis-of-joe-bidens-tax-proposals/} +} + +@Article{DeBackerFrailey:2019, + author={Jason DeBacker and Anderson Frailey}, + title={Revenue and Macroeconomic Effects of a 70% Marginal Tax Rate}, + journal={Quantitative Notes}, + year=2019, + volume={}, + number={2019-1}, + pages={}, + month={March}, + keywords={}, + doi={}, + abstract={Recently, there has been considerable dis- cussion of a significant increase in the top marginal income tax rate. A salient top marginal tax rate is 70%. This note simulates the effects of a 70% top rate on different groups of filers and shows the im- pacts on revenue and macroeconomic aggregates. We find that an increase in the top marginal tax rate to 70% raises between $5 billion and $250 billion per year over the first 10 years, depending on the size of the top bracket to which this rate is applied. However, our macroeconomic simulations show that a 70% top rate lowers GDP by between 1.7% and 0.1% in the near term, although there may be posi- tive effects on GDP in the longer term.}, + url={https://www.openrg.com/reports/70pctMTR_QN.pdf} +} + +@Article{Evans:2018, + author={Richard W. Evans}, + title={Dynamic Analysis of EITC Expansion}, + journal={Quantitative Notes}, + year=2018, + volume={}, + number={2018-2}, + pages={}, + month={May}, + keywords={}, + doi={}, + abstract={This Quantitative Note uses the OG-USA open source dynamic general equilibrium overlap- ping generations model to perform a dynamic analy- sis of the Brown-Khanna Grow American Incomes Now (GAIN) Act, which proposes to increase the generosity and scope of the earned income tax credit (EITC) in the United States. I show a simulation of the macroeconomic effects as well as distributional analysis resulting from the GAIN Act. I also sim- ulate the effects of a revenue neutral GAIN Act in which an increase in the marginal income tax rates in the top two personal income brackets exactly off- sets the reduction in total federal tax revenue from the EITC expansion. In the case of the GAIN Act alone, the economy experiences short-run gains, but the increased government debt quickly crowds out in- vestment and causes the economy to start shrinking significantly. In the revenue neutral case, the cost is primarily in terms of large labor supply frictions and a reallocation of the household labor-leisure and consumption-savings decisions.}, + url={https://www.openrg.com/reports/QN_EITC_v1.1.pdf} +} + +@Article{DeBackerEvans:2018, + author={Jason DeBacker and Richard W. Evans}, + title={Dynamic Analysis of Tax Cuts and Jobs Act}, + journal={Quantitative Notes}, + year=2018, + volume={}, + number={2018-1}, + pages={}, + month={February}, + keywords={}, + doi={}, + abstract={This Quantitative Note uses the OG-USA open source dynamic general equilibrium overlap- ping generations model to simulate the effect of the Tax Cuts and Jobs Act. We simulate this reform under the assumptions of a closed economy and small open economy. In both cases, the TCJA reform causes significant growth in GDP and employment between 1% and 2% per year in the first 8 years. However, the increasing debt-to-GDP ratio quickly crowds out investment and causes a drag on the economy. Wage growth can range from nearly nonexistent to a mod- est 0.6%, depending critically on the assumption of how much capital will flow into the country.}, + url={https://www.openrg.com/reports/QN_ogusa_TCJA.pdf} +} + +@Article{Evans:2017, + author={Richard W. Evans}, + title={Dynamic Analysis of Corporate Income Tax Rate Cut}, + journal={Quantitative Notes}, + year=2017, + volume={}, + number={2017-4}, + pages={}, + month={November}, + keywords={}, + doi={}, + abstract={This Quantitative Note uses the OG-USA open source dynamic general equilibrium overlap- ping generations model to simulate the effect of cut- ting the U.S. corporate income tax rate from 35% to 20%. I simulate this rate cut under the assump- tions of a closed economy and small open economy, respectively. In both cases, the corporate rate cut causes government revenues to decrease and the debt-to-GDP ratio to increase. In the small open economy scenario, GDP and wages increase by around 3.0%, and 2.5%, respectively. However, in the closed economy setting in which the increased debt service must be satisfied by domestic savings (crowding out), the GDP and wage gains are much smaller and short lived.}, + url={https://www.openrg.com/reports/QN_CorpCut.pdf} +} + +@TECHREPORT{DEP:2015, + AUTHOR = {Jason DeBacker and Richard W. Evans and Kerk L. Phillips}, + TITLE = {Macroeconomic effects of a 10% cut in statutory marginal income tax rates on ordinary income}, + INSTITUTION = {American Enterprise Institute}, + YEAR = {2015}, + type = {AEI Economic Policy Working Paper Series}, + month = {December}, +} + +@Article{Ferenstein:2018, + author={Gregory Ferenstein}, + title={Can The U.S. Afford A Massive Wage Subsidy? A Macroeconomic Simulation}, + journal={Forbes}, + year=2018, + volume={}, + number={}, + pages={}, + month={September}, + keywords={}, + doi={}, + abstract={}, + url={https://www.forbes.com/sites/gregoryferenstein/2018/09/30/can-the-us-afford-a-massive-wage-subsidy-a-macroeconomic-simulation/#614ea9032502} +} + +@TECHREPORT{MichelFurth:2017b, + AUTHOR = {Adam Michel and Salim Furth}, + TITLE = {For Pro-Growth Tax Reform, Expensing Should Be the Focus}, + INSTITUTION = {The Heritage Foundation}, + YEAR = {2017}, + type = {Taxes Report}, + month = {August}, + url = {https://www.heritage.org/taxes/report/pro-growth-tax-reform-expensing-should-be-the-focus} +} + +@TECHREPORT{MichelFurth:2017a, + AUTHOR = {Norbert Michel and Salim Furth}, + TITLE = {The Macroeconomic Impact of Dodd Frank—and of Its Repeal}, + INSTITUTION = {The Heritage Foundation}, + YEAR = {2017}, + type = {Taxes Report}, + month = {April}, + url = {https://www.heritage.org/markets-and-finance/report/the-macroeconomic-impact-dodd-frank-and-its-repeal} +} + +@TECHREPORT{Hassett:2015, + AUTHOR = {Kevin A. Hassett}, + TITLE = {On the Dynamic Scoring of Fiscal Policy}, + INSTITUTION = {}, + YEAR = {2015}, + type = {Congressional Testimony}, + month = {July}, + url = {https://www.aei.org/wp-content/uploads/2015/07/Hassett_DynamicScoring_final-00000002.pdf} +} + +@TECHREPORT{Hassett:2016, + AUTHOR = {Kevin A. Hassett}, + TITLE = {Statement before the House Ways and Means Committee: Reaching America’s Potential: Delivering Growth and Opportunity for All Americans}, + INSTITUTION = {}, + YEAR = {2016}, + type = {Congressional Testimony}, + month = {February}, + url = {https://www.aei.org/wp-content/uploads/2016/02/KHtestimony.pdf} +} + +@TECHREPORT{DEP:2021a, + AUTHOR = {Jason DeBacker and Richard W. Evans and Benjamin R. Page}, + TITLE = {A Detailed Macroeconomic Analysis of President Biden's 2020 Campaign Tax Proposals}, + INSTITUTION = {Tax Policy Center}, + YEAR = {2021}, + type = {Working Paper}, + month = {July}, + url = {https://www.taxpolicycenter.org/publications/detailed-macroeconomic-analysis-president-bidens-2020-campaign-tax-proposals} +} + +@TECHREPORT{DEP:2021b, + AUTHOR = {Jason DeBacker and Richard W. Evans and Benjamin R. Page}, + TITLE = {A Sensitivity Analysis of a Detailed Macroeconomic Analysis of President Biden's 2020 Campaign Tax Proposals}, + INSTITUTION = {Tax Policy Center}, + YEAR = {2021}, + type = {Working Paper}, + month = {July}, + url = {https://www.taxpolicycenter.org/publications/sensitivity-analysis-detailed-macroeconomic-analysis-president-bidens-2020-campaign-tax} +} + +@TECHREPORT{DEP:2021c, + AUTHOR = {Benjamin R. Page and Jeffrey Rohaly and Thornton Matheson and Gordon B. Mermin and Jason DeBacker and Richard W. Evans}, + TITLE = {Macroeconomic Analysis of Former Vice President Biden's Tax Proposals}, + INSTITUTION = {Tax Policy Center}, + YEAR = {2021}, + type = {Brief}, + month = {July}, + url = {https://www.taxpolicycenter.org/publications/macroeconomic-analysis-former-vice-president-bidens-tax-proposals} +} + +@TECHREPORT{Page:2021, + AUTHOR = {Benjamin R. Page}, + TITLE = {TPC Experiments with Another Model to Estimate the Economic Effects of Tax Law Changes}, + INSTITUTION = {Tax Policy Center}, + YEAR = {2021}, + type = {TaxVox: Campaigns, Proposals, and Reforms}, + month = {July}, + url = {https://www.taxpolicycenter.org/taxvox/tpc-experiments-another-model-estimate-economic-effects-tax-law-changes} +} diff --git a/docs/book/content/OGUSA_references.md b/docs/book/content/OGUSA_references.md new file mode 100644 index 00000000..903a0050 --- /dev/null +++ b/docs/book/content/OGUSA_references.md @@ -0,0 +1,5 @@ +# References + +```{bibliography} ../OGUSA_references.bib +:style: plain +``` diff --git a/docs/book/content/api/bequest_transmission.rst b/docs/book/content/api/bequest_transmission.rst index 1e6e6beb..2785bd40 100644 --- a/docs/book/content/api/bequest_transmission.rst +++ b/docs/book/content/api/bequest_transmission.rst @@ -3,12 +3,10 @@ Bequest Transmission Process Estimation Functions ================================================= -**Bequest Transmission Process Estimation Functions** +**bequest_transmission.py modules** -ogusa_calibrate.bequest_transmission +ogusa.bequest_transmission ------------------------------------------ -.. currentmodule:: ogusa_calibrate.bequest_transmission - -.. automodule:: ogusa_calibrate.bequest_transmission +.. automodule:: ogusa.bequest_transmission :members: MVKDE, get_bequest_matrix diff --git a/docs/book/content/api/calibrate.rst b/docs/book/content/api/calibrate.rst index 5a2a10bf..177a3221 100644 --- a/docs/book/content/api/calibrate.rst +++ b/docs/book/content/api/calibrate.rst @@ -3,12 +3,12 @@ Main Calibration Functions ================================================= -**Main Calibration Functions** +**calibrate.py classes, methods, and modules** -ogusa_calibrate.calibrate +ogusa.calibrate ------------------------------------------ -.. currentmodule:: ogusa_calibrate.calibrate +.. currentmodule:: ogusa.calibrate -.. automodule:: Calibrate +.. autoclass:: Calibration :members: get_tax_function_parameters, read_tax_func_estimate, get_dict diff --git a/docs/book/content/api/demographics.rst b/docs/book/content/api/demographics.rst index a6aa6b3f..6daa40bb 100644 --- a/docs/book/content/api/demographics.rst +++ b/docs/book/content/api/demographics.rst @@ -3,13 +3,11 @@ Demographics Functions ======================== -**Demographics** +**demographics.py modules** ogusa.demographics ------------------------------------------ -.. currentmodule:: ogusa.demographics - .. automodule:: ogusa.demographics :members: get_fert, get_mort, pop_rebin, get_imm_resid, immsolve, get_pop_objs diff --git a/docs/book/content/api/deterministic_profiles.rst b/docs/book/content/api/deterministic_profiles.rst index 50e0d0e9..5c0d5628 100644 --- a/docs/book/content/api/deterministic_profiles.rst +++ b/docs/book/content/api/deterministic_profiles.rst @@ -3,12 +3,10 @@ Deterministic Earnings Profiles Estimation Functions ==================================================== -**Deterministic Earnings Profiles Estimation Functions** +**deterministic_profiles.py modules** -ogusa_calibrate.deterministic_profiles +ogusa.deterministic_profiles ------------------------------------------ -.. currentmodule:: ogusa_calibrate.deterministic_profiles - -.. automodule:: ogusa_calibrate.deterministic_profiles +.. automodule:: ogusa.deterministic_profiles :members: estimate_profiles diff --git a/docs/book/content/api/estimate_beta_j.rst b/docs/book/content/api/estimate_beta_j.rst index f966ad11..3e2c2193 100644 --- a/docs/book/content/api/estimate_beta_j.rst +++ b/docs/book/content/api/estimate_beta_j.rst @@ -3,13 +3,11 @@ Beta Estimation Functions ========================= -**Beta Estimation Functions** +**estimate_beta_j.py modules** -ogusa_calibrate.estimate_beta_j +ogusa.estimate_beta_j ------------------------------------------ -.. currentmodule:: ogusa_calibrate.estimate_beta_j - -.. automodule:: ogusa_calibrate.estimate_beta_j +.. automodule:: ogusa.estimate_beta_j :members: beta_estimate, minstat, calc_moments, compute_weighting_matrix, VCV_moments, compute_se diff --git a/docs/book/content/api/get_micro_data.rst b/docs/book/content/api/get_micro_data.rst index 44166a0c..fe073e1e 100644 --- a/docs/book/content/api/get_micro_data.rst +++ b/docs/book/content/api/get_micro_data.rst @@ -1,14 +1,12 @@ .. _get_micro_data: -Functions to Get Micro-data from Tax-Calculator +Functions to Get Micro-data ================================================= -**Get Micro-data Functions** +**get_micro_data.py modules** -ogusa_calibrate.get_micro_data +ogusa.get_micro_data ------------------------------------------ -.. currentmodule:: ogusa_calibrate.get_micro_data - -.. automodule:: ogusa_calibrate.get_micro_data +.. automodule:: ogusa.get_micro_data :members: get_calculator, get_data, taxcalc_advance, cap_inc_mtr diff --git a/docs/book/content/api/income.rst b/docs/book/content/api/income.rst index c5d9837e..ed488a88 100644 --- a/docs/book/content/api/income.rst +++ b/docs/book/content/api/income.rst @@ -1,15 +1,13 @@ .. _income: -Income Processes Functions +Income Process Functions ================================================= -**Income Processes Functions** +**income.py modules** -ogusa_calibrate.income +ogusa.income ------------------------------------------ -.. currentmodule:: ogusa_calibrate.income - -.. automodule:: ogusa_calibrate.income +.. automodule:: ogusa.income :members: arctan_func, arctan_deriv_func, arc_error, arctan_fit, get_e_interp, get_e_orig diff --git a/docs/book/content/api/macro_params.rst b/docs/book/content/api/macro_params.rst index 1d79f684..7b7d4852 100644 --- a/docs/book/content/api/macro_params.rst +++ b/docs/book/content/api/macro_params.rst @@ -3,12 +3,10 @@ Macro Parameter Estimation Functions ==================================== -**Macro Parameter Estimation Functions** +**macro_params.py modules** -ogusa_calibrate.macro_params +ogusa.macro_params ------------------------------------------ -.. currentmodule:: ogusa_calibrate.macro_params - -.. automodule:: ogusa_calibrate.macro_params +.. automodule:: ogusa.macro_params :members: get_macro_params diff --git a/docs/book/content/api/public_api.rst b/docs/book/content/api/public_api.rst index 716232b4..3f99d71d 100644 --- a/docs/book/content/api/public_api.rst +++ b/docs/book/content/api/public_api.rst @@ -1,10 +1,10 @@ API ========================= -The source code for `OG-USA-Calibration` is located in the `OG-USA-Calibration/ogusa_calibrate` 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-Calibration` package, with links +Here we provide a high-level view of the API of the `OG-USA` package, with links to the source code. This high-level view is organized around the modules that -make up the `OG-USA-Calibration` package. Below is a list of these modules (in alphabetical +make up the `OG-USA` package. 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. @@ -20,4 +20,3 @@ There is also a link to the source code for each documented member. income macro_params transfer_distribution - txfunc diff --git a/docs/book/content/api/transfer_distribution.rst b/docs/book/content/api/transfer_distribution.rst index c1f0f102..fb6d9d77 100644 --- a/docs/book/content/api/transfer_distribution.rst +++ b/docs/book/content/api/transfer_distribution.rst @@ -3,12 +3,10 @@ Government Transfer Distribution Estimation Functions ===================================================== -**Government Transfer Distribution Estimation Functions** +**transfer_distribution.py modules** -ogusa_calibrate.transfer_distribution +ogusa.transfer_distribution ------------------------------------------ -.. currentmodule:: ogusa_calibrate.transfer_distribution - -.. automodule:: ogusa_calibrate.transfer_distribution +.. automodule:: ogusa.transfer_distribution :members: MVKDE, get_transfer_matrix diff --git a/docs/book/content/api/txfunc.rst b/docs/book/content/api/txfunc.rst deleted file mode 100644 index 537d1d20..00000000 --- a/docs/book/content/api/txfunc.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _txfunc: - -Tax Function Estimation Functions -================================================= - -**Tax Function Estimation Functions** - -ogusa_calibrate.txfunc ------------------------------------------- - -.. currentmodule:: ogusa_calibrate.txfunc - -.. automodule:: ogusa_calibrate.txfunc - :members: get_tax_rates, wsumsq, find_outliers, replace_outliers, - txfunc_est, tax_func_loop, tax_func_estimate, get_tax_func_estimate diff --git a/docs/book/content/calibration/UBI.md b/docs/book/content/calibration/UBI.md index 6e1a16b9..60456472 100644 --- a/docs/book/content/calibration/UBI.md +++ b/docs/book/content/calibration/UBI.md @@ -3,25 +3,24 @@ [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`. +We have included the modeling of a universal basic income (UBI) policy directly in the theory and code for [`OG-Core`] on which dependency the `OG-USA` is based. UBI shows up in the household budget constraint {eq}`EqHHBC`, and is described in the [Budget Constraint](https://pslmodels.github.io/OG-Core/content/theory/households.html#budget-constraint) section of the Households chapter of the `OG-Core` documentation. 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. + 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 [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/ogusa_default_parameters.json) file (`ubi_growthadj`, `ubi_nom_017`, `ubi_nom_1864`, `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 `Calibrate` class of the `OG-USA/ogusa/calibrate.py` module in the 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] + From the [OG-USA](https://github.com/PSLmodels/OG-USA) repository, we have four $S\times J$ matrices `ubi_num_017_mat`$_{j,s}$, `ubi_num_1864_mat`$_{j,s}$, and `ubi_num_65p_mat`$_{j,s}$ representing the number of children under age 0-17, number of adults ages 18-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. + 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_1864` be the dollar value of the UBI transfer to each household per adult between the ages of 18 and 64. Let `ubi_nom_65p` be the dollar value of UBI transfer to each household per senior 65 and over. 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_1864} * \texttt{ubi_num_1864_mat}_{j,s} + \\ &\texttt{ubi_nom_65p} * \texttt{ubi_num_65p_mat}_{j,s}\Bigr) \quad\forall j,s \end{split} ``` @@ -39,7 +38,7 @@ We have included the modeling of a universal basic income (UBI) policy directly 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$. + As described in the [OG-Core chapter on stationarization](https://pslmodels.github.io/OG-Core/content/theory/stationarization.html), 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 @@ -60,4 +59,4 @@ We have included the modeling of a universal basic income (UBI) policy directly [^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. +[^GrowthAdj_note]: We impose this requirement of `ubi_growthadj = False` when `g_y_annual < 0` in the [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/ogusa_default_parameters.json) "validators" specification of the parameter. diff --git a/docs/book/content/calibration/bequests.md b/docs/book/content/calibration/bequests.md index 2102ca34..3ed68f19 100644 --- a/docs/book/content/calibration/bequests.md +++ b/docs/book/content/calibration/bequests.md @@ -3,6 +3,6 @@ [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`. +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 {eq}`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`. diff --git a/docs/book/content/calibration/demographics.md b/docs/book/content/calibration/demographics.md index c8bf682a..69aa3dc8 100644 --- a/docs/book/content/calibration/demographics.md +++ b/docs/book/content/calibration/demographics.md @@ -8,11 +8,9 @@ jupytext: kernelspec: display_name: Python 3 language: python - name: ogusa-calibrate-dev + name: ogusa-dev --- -(glue)= - (Chap_Demog)= # Demographics @@ -56,7 +54,7 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r (SecDemogFert)= ## Fertility rates - In `OG-USA`, we assume that the fertility rates for each age cohort $f_s$ are constant across time. However, this assumption is conceptually straightforward to relax. Our data for U.S. fertility rates by age come from {cite}`MartinEtAl:2015` National Vital Statistics Report, which is final fertility rate data for 2013. Figure {numref}`FigFertRates` shows the fertility-rate data and the estimated average fertility rates for $E+S=100$. + In `OG-USA`, we assume that the fertility rates for each age cohort $f_s$ are constant across time. However, this assumption is conceptually straightforward to relax. Our data for U.S. fertility rates by age come from {cite}`MartinEtAl:2015` National Vital Statistics Report, which is final fertility rate data for 2013. {numref}`Figure %s ` shows the fertility-rate data and the estimated average fertility rates for $E+S=100$. ```{figure} ./images/fert_rates.png --- @@ -66,14 +64,14 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r Fertility rates by age ($f_s$) for $E+S=100$ ``` - The large blue circles are the 2013 U.S. fertility rate data from {cite}`MartinEtAl:2015`. These are 9 fertility rates [0.3, 12.3, 47.1, 80.7, 105.5, 98.0, 49.3, 10.4, 0.8] that correspond to the midpoint ages of the following age (in years) bins [10-14, 15-17, 18-19, 20-24, 25-29, 30-34, 35-39, 40-44, 45-49]. In order to get our cubic spline interpolating function to fit better at the endpoints we added to fertility rates of zero to ages 9 and 10, and we added two fertility rates of zero to ages 55 and 56. The blue line in Figure {numref}`FigFertRates` shows the cubic spline interpolated function of the data. + The large blue circles are the 2013 U.S. fertility rate data from {cite}`MartinEtAl:2015`. These are 9 fertility rates [0.3, 12.3, 47.1, 80.7, 105.5, 98.0, 49.3, 10.4, 0.8] that correspond to the midpoint ages of the following age (in years) bins [10-14, 15-17, 18-19, 20-24, 25-29, 30-34, 35-39, 40-44, 45-49]. In order to get our cubic spline interpolating function to fit better at the endpoints we added to fertility rates of zero to ages 9 and 10, and we added two fertility rates of zero to ages 55 and 56. The blue line in {numref}`Figure %s ` shows the cubic spline interpolated function of the data. - The red diamonds in Figure {numref}`FigFertRates` are the average fertility rate in age bins spanning households born at the beginning of period 1 (time = 0) and dying at the end of their 100th year. Let the total number of model years that a household lives be $E+S\leq 100$. Then the span from the beginning of period 1 (the beginning of year 0) to the end of period 100 (the end of year 99) is divided up into $E+S$ bins of equal length. We calculate the average fertility rate in each of the $E+S$ model-period bins as the average population-weighted fertility rate in that span. The red diamonds in Figure {numref}`FigFertRates` are the average fertility rates displayed at the midpoint in each of the $E+S$ model-period bins. + The red diamonds in {numref}`Figure %s ` are the average fertility rate in age bins spanning households born at the beginning of period 1 (time = 0) and dying at the end of their 100th year. Let the total number of model years that a household lives be $E+S\leq 100$. Then the span from the beginning of period 1 (the beginning of year 0) to the end of period 100 (the end of year 99) is divided up into $E+S$ bins of equal length. We calculate the average fertility rate in each of the $E+S$ model-period bins as the average population-weighted fertility rate in that span. The red diamonds in {numref}`Figure %s ` are the average fertility rates displayed at the midpoint in each of the $E+S$ model-period bins. (SecDemogMort)= ## Mortality rates - The mortality rates in our model $\rho_s$ are a one-period hazard rate and represent the probability of dying within one year, given that an household is alive at the beginning of period $s$. We assume that the mortality rates for each age cohort $\rho_s$ are constant across time. The infant mortality rate of $\rho_0=0.00587$ comes from the 2015 U.S. CIA World Factbook. Our data for U.S. mortality rates by age come from the Actuarial Life Tables of the U.S. Social Security Administration {cite}`SocSec:2015`, from which the most recent mortality rate data is for 2011. Figure {numref}`FigMortRates` shows the mortality rate data and the corresponding model-period mortality rates for $E+S=100$. + The mortality rates in our model $\rho_s$ are a one-period hazard rate and represent the probability of dying within one year, given that an household is alive at the beginning of period $s$. We assume that the mortality rates for each age cohort $\rho_s$ are constant across time. The infant mortality rate of $\rho_0=0.00587$ comes from the 2015 U.S. CIA World Factbook. Our data for U.S. mortality rates by age come from the Actuarial Life Tables of the U.S. Social Security Administration {cite}`SocSec:2015`, from which the most recent mortality rate data is for 2011. {numref}`Figure %s ` shows the mortality rate data and the corresponding model-period mortality rates for $E+S=100$. ```{figure} ./images/mort_rates.png --- @@ -103,7 +101,7 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r --> - The mortality rates in Figure {numref}`FigMortRates` are a population-weighted average of the male and female mortality rates reported in {cite}`SocSec:2015`. Figure {numref}`FigMortRates` also shows that the data provide mortality rates for ages up to 111-years-old. We truncate the maximum age in years in our model to 100-years old. In addition, we constrain the mortality rate to be 1.0 or 100 percent at the maximum age of 100. + The mortality rates in {numref}`Figure %s ` are a population-weighted average of the male and female mortality rates reported in {cite}`SocSec:2015`. {numref}`Figure %s ` also shows that the data provide mortality rates for ages up to 111-years-old. We truncate the maximum age in years in our model to 100-years old. In addition, we constrain the mortality rate to be 1.0 or 100 percent at the maximum age of 100. (SecDemogImm)= ## Immigration rates @@ -143,7 +141,7 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r ``` --> - We calculate our immigration rates for three different consecutive-year-periods of population distribution data (2010 through 2013). Our four years of population distribution by age data come from {cite}`Census:2015`. The immigration rates $i_s$ that we use in our model are the the residuals described in {eq}`EqPopImmRates` averaged across the three periods. Figure {numref}`FigImmRates` shows the estimated immigration rates for $E+S=100$ and given the fertility rates from Section {ref}`SecDemogFert` and the mortality rates from Section {ref}`SecDemogMort`. + We calculate our immigration rates for three different consecutive-year-periods of population distribution data (2010 through 2013). Our four years of population distribution by age data come from {cite}`Census:2015`. The immigration rates $i_s$ that we use in our model are the the residuals described in {eq}`EqPopImmRates` averaged across the three periods. {numref}`Figure %s ` shows the estimated immigration rates for $E+S=100$ and given the fertility rates from Section {ref}`SecDemogFert` and the mortality rates from Section {ref}`SecDemogMort`. At the end of Section {ref}`SecDemogPopSSTP`, we describe a small adjustment that we make to the immigration rates after a certain number of periods in order to make computation of the transition path equilibrium of the model compute more robustly. @@ -251,7 +249,7 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r For a full treatment and proof of the Perron-Frobenius Theorem, see {cite}`Suzumura:1983`. Because the population growth process is exogenous to the model, we calibrate it to annual age data for age years $s=1$ to $s=100$. - Figure {numref}`FigOrigVsFixSSpop` shows the steady-state population distribution $\boldsymbol{\bar{\omega}}$ and the population distribution after 120 periods $\boldsymbol{\hat{\omega}}_{120}$. Although the two distributions look very close to each other, they are not exactly the same. + {numref}`Figure %s ` shows the steady-state population distribution $\boldsymbol{\bar{\omega}}$ and the population distribution after 120 periods $\boldsymbol{\hat{\omega}}_{120}$. Although the two distributions look very close to each other, they are not exactly the same. ```{figure} ./images/OrigVsFixSSpop.png --- @@ -261,7 +259,7 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r Theoretical steady-state population distribution vs. population distribution at period $t=120$ ``` - Further, we find that the maximum absolute difference between the population levels $\hat{\omega}_{s,t}$ and $\hat{\omega}_{s,t+1}$ was $1.3852\times 10^{-5}$ after 160 periods. That is to say, that after 160 periods, given the estimated mortality, fertility, and immigration rates, the population has not achieved its steady state. For convergence in our solution method over a reasonable time horizon, we want the population to reach a stationary distribution after $T$ periods. To do this, we artificially impose that the population distribution in period $t=120$ is the steady-state. As can be seen from Figure {numref}`FigOrigVsFixSSpop`, this assumption is not very restrictive. Figure {numref}`FigImmRateChg` shows the change in immigration rates that would make the period $t=120$ population distribution equal be the steady-state. The maximum absolute difference between any two corresponding immigration rates in Figure {numref}`FigImmRateChg` is 0.0028. + Further, we find that the maximum absolute difference between the population levels $\hat{\omega}_{s,t}$ and $\hat{\omega}_{s,t+1}$ was $1.3852\times 10^{-5}$ after 160 periods. That is to say, that after 160 periods, given the estimated mortality, fertility, and immigration rates, the population has not achieved its steady state. For convergence in our solution method over a reasonable time horizon, we want the population to reach a stationary distribution after $T$ periods. To do this, we artificially impose that the population distribution in period $t=120$ is the steady-state. As can be seen from {numref}`Figure %s `, this assumption is not very restrictive. {numref}`Figure %s ` shows the change in immigration rates that would make the period $t=120$ population distribution equal be the steady-state. The maximum absolute difference between any two corresponding immigration rates in {numref}`Figure %s ` is 0.0028. ```{figure} ./images/OrigVsAdjImm.png --- @@ -271,7 +269,7 @@ We discuss the approach to estimating fertility rates $f_s$, mortality rates $\r Original immigration rates vs. adjusted immigration rates to make fixed steady-state population distribution ``` - The most recent year of population data come from {cite}`Census:2015` population estimates for both sexes for 2013. We those data and use the population transition matrix {eq}`EqPopLOMstatmat2` to age it to the current model year of 2015. We then use {eq}`EqPopLOMstatmat2` to generate the transition path of the population distribution over the time period of the model. Figure {numref}`FigPopDistPath` shows the progression from the 2013 population data to the fixed steady-state at period $t=120$. The time path of the growth rate of the economically active population $\tilde{g}_{n,t}$ is shown in Figure {numref}`FigGrowthPath`. + The most recent year of population data come from {cite}`Census:2015` population estimates for both sexes for 2013. We those data and use the population transition matrix {eq}`EqPopLOMstatmat2` to age it to the current model year of 2015. We then use {eq}`EqPopLOMstatmat2` to generate the transition path of the population distribution over the time period of the model. {numref}`Figure %s ` shows the progression from the 2013 population data to the fixed steady-state at period $t=120$. The time path of the growth rate of the economically active population $\tilde{g}_{n,t}$ is shown in {numref}`Figure %s `. ```{figure} ./images/PopDistPath.png --- diff --git a/docs/book/content/calibration/earnings.md b/docs/book/content/calibration/earnings.md index 6df10eeb..276973b2 100644 --- a/docs/book/content/calibration/earnings.md +++ b/docs/book/content/calibration/earnings.md @@ -8,11 +8,9 @@ jupytext: kernelspec: display_name: Python 3 language: python - name: ogusa-calibrate-dev + name: ogusa-dev --- -(glue)= - (Chap_LfEarn)= # Lifetime Earnings Profiles @@ -21,7 +19,7 @@ Among households in `OG-USA`, we model both age heterogeneity and within-age abi Differences among workers' productivity in terms of ability is one of the key dimensions of heterogeneity to model in a micro-founded macroeconomy. In this chapter, we characterize this heterogeneity as deterministic lifetime productivity paths to which new cohorts of agents in the model are randomly assigned. In `OG-USA`, households' labor income comes from the equilibrium wage and the agent's endogenous quantity of labor supply. In this section, we augment the labor income expression with an individual productivity $e_{j,s}$, where $j$ is the index of the ability type or path of the individual and $s$ is the age of the individual with that ability path. ```{math} -:label: EqTaxCalcLabInc +:label: EqLaborIncome \text{labor income:}\quad x_{j,s,t}\equiv w_t e_{j,s}n_{j,s,t} \quad\forall j,t \quad\text{and}\quad E+1\leq s\leq E+S ``` @@ -57,10 +55,11 @@ 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:2017` extrapolate these estimates for model ages 80-100 using an arctan function. +{numref}`Figure %s ` 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). + (SecLFEarnCWHS)= ## Continuous Work History Sample @@ -301,7 +300,7 @@ We calibrate the model such that each lifetime income group has a different life ln(w_{j,t}) = \alpha_{j} + \beta_{1}age_{j,t} + \beta_{2}age_{j,t}^{2} + \beta_{3}*age_{j,t}^{3} + \varepsilon_{j,t} ``` - The estimated parameters from equation {eq}`EqWage_profile` are given in {numref}`TabWage_profiles`. The life-cycle earnings profiles implied by these parameters are plotted in {numref}`FigLogAbil`. Note that there are few individuals above age 80 in the data. To extrapolate these estimates for model ages 80-100, we use an arctan function of the following form: + The estimated parameters from equation {eq}`EqWage_profile` are given in {numref}`TabWage_profiles`. The life-cycle earnings profiles implied by these parameters are plotted in {numref}`Figure %s `. Note that there are few individuals above age 80 in the data. To extrapolate these estimates for model ages 80-100, we use an arctan function of the following form: ```{math} :label: EqLfEarnArctan y = \left(\frac{-a}{\pi}\right)*arctan(bx+c)+\frac{a}{2} diff --git a/docs/book/content/calibration/exogenous_parameters.md b/docs/book/content/calibration/exogenous_parameters.md index 70e55c8e..a0d46ada 100644 --- a/docs/book/content/calibration/exogenous_parameters.md +++ b/docs/book/content/calibration/exogenous_parameters.md @@ -8,10 +8,9 @@ jupytext: kernelspec: display_name: Python 3 language: python - name: ogusa-calibrate-dev + name: ogusa-dev --- -(glue)= (Chap_Exog)= # Exogenous Parameters diff --git a/docs/book/content/calibration/macro.md b/docs/book/content/calibration/macro.md index e0f1614d..b8a23790 100644 --- a/docs/book/content/calibration/macro.md +++ b/docs/book/content/calibration/macro.md @@ -5,7 +5,7 @@ ### Elasticity of labor supply -As we discuss in Chapter {ref}`Chap_House`, we use the elliptical disutility of labor function developed by {cite}`EvansPhillips:2017`. We then fit the parameters of the elliptical utility function to match the marginal disutility from a constant Frisch elasticity function. `OG-USA` users enter the constant Frisch elasticity as a parameter. {cite}`Peterman:2016` finds a range of Frisch elasticities estimated from microeconomic and macroeconomic data. These range from 0 to 4. Peterman makes the case that in lifecycle models with out an extensive margin for employment, such as `OG-USA`, the Frisch elasticity should be higher. We take a default value of 0.4 from {cite}`Altonji:1986`. +As discussed in the [OG-Core household theory documentation](https://pslmodels.github.io/OG-Core/content/theory/households.html), we use the elliptical disutility of labor function developed by {cite}`EvansPhillips:2017`. We then fit the parameters of the elliptical utility function to match the marginal disutility from a constant Frisch elasticity function. `OG-USA` users enter the constant Frisch elasticity as a parameter. {cite}`Peterman:2016` finds a range of Frisch elasticities estimated from microeconomic and macroeconomic data. These range from 0 to 4. Peterman makes the case that in lifecycle models with out an extensive margin for employment, such as `OG-USA`, the Frisch elasticity should be higher. We take a default value of 0.4 from {cite}`Altonji:1986`. ### Intertemporal elasticity of substitution @@ -22,7 +22,7 @@ As the default rate of labor augmenting technological change, $g_y$, we use a va ## Aggregate Production Function and Capital Accumulation -Chapter {ref}`Chap_Firms` outlines the constant returns to scale, constant elasticity of substitution production function of the representative firm. This function has two parameters; the elasticity of substitution and capital's share of output. +The [OG-Core firm theory documentation](https://pslmodels.github.io/OG-Core/content/theory/firms.html) outlines the constant returns to scale, constant elasticity of substitution production function of the representative firm. This function has two parameters; the elasticity of substitution and capital's share of output. ### Elasticity of substitution diff --git a/docs/book/content/calibration/references.md b/docs/book/content/calibration/references.md deleted file mode 100644 index 83a8c6a6..00000000 --- a/docs/book/content/calibration/references.md +++ /dev/null @@ -1,5 +0,0 @@ -# References - -```{bibliography} ../../OGUSA_references.bib -:style: alpha -``` diff --git a/docs/book/content/calibration/tax_functions.md b/docs/book/content/calibration/tax_functions.md index 59e00bdb..8d16ddc7 100644 --- a/docs/book/content/calibration/tax_functions.md +++ b/docs/book/content/calibration/tax_functions.md @@ -3,7 +3,14 @@ The government is not an optimizing agent in `OG-USA`. The government levies taxes on households, provides transfers to households, levies taxes on firms, spends resources on public goods, and makes rule-based adjustments to stabilize the economy in the long-run. The government can run budget deficits or surpluses in a given year and must, therefore, be able to accumulate debt or savings. -The government sector influences households through two terms in the budget constraint {eq}`EqHHBC`---government transfers $TR_{t}$ and through the total tax liability function $T_{s,t}$, which can be decomposed into the effective tax rate times total income {eq}`EqTaxCalcLiabETR`. In this chapter, we detail the household tax component of government activity $T_{s,t}$ in `OG-USA`, along with our method of incorporating detailed microsimulation data into a dynamic general equilibrium model. +The government sector influences households through two terms in the household budget constraint {eq}`EqHHBC`---government transfers $TR_{t}$ and through the total tax liability function $T_{s,t}$, which can be decomposed into the effective tax rate times total income {eq}`EqTaxCalcLiabETR2`. In this chapter, we detail the household tax component of government activity $T_{s,t}$ in `OG-USA`, along with our method of incorporating detailed microsimulation data into a dynamic general equilibrium model. + +```{math} +:label: EqHHBC + c_{j,s,t} + b_{j,s+1,t+1} &= (1 + r_{hh,t})b_{j,s,t} + w_t e_{j,s} n_{j,s,t} + \\ + &\quad\quad\zeta_{j,s}\frac{BQ_t}{\lambda_j\omega_{s,t}} + \eta_{j,s,t}\frac{TR_{t}}{\lambda_j\omega_{s,t}} + ubi_{j,s,t} - T_{s,t} \\ + &\quad\forall j,t\quad\text{and}\quad s\geq E+1 \quad\text{where}\quad b_{j,E+1,t}=0\quad\forall j,t +``` Incorporating realistic tax and incentive detail into a general equilibrium model is notoriously difficult for two reasons. First, it is impossible in a dynamic general equilibrium model to capture all of the dimensions of heterogeneity on which the real-world tax rate depends. For example, a household's tax liability in reality depends on filing status, number of dependents, many types of income, and some characteristics correlated with age. A good heterogeneous agent DGE model tries to capture the most important dimensions of heterogeneity, and necessarily neglects the other dimensions. @@ -45,7 +52,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need \tau^{mtry} \equiv \frac{\partial T_{s,t}}{\partial r_{hh,t}b_{j,s,t}} = \frac{\partial T_{s,t}}{\partial y_{j,s,t}} \qquad\quad\forall j,t \quad\text{and}\quad E+1\leq s\leq E+S ``` - As we show in Section {ref}`SecHHeulers`, the derivative of total tax liability with respect to labor supply $\frac{\partial T_{s,t}}{n_{j,s,t}}$ and the derivative of total tax liability next period with respect to savings $\frac{\partial T_{s+1,t+1}}{b_{j,s+1,t+1}}$ show up in the household Euler equations for labor supply {eq}`EqHHeul_n` and savings {eq}`EqHHeul_b`, respectively. It is valuable to be able to express those marginal tax rates, for which we have no data, as marginal tax rates for which we do have data. The following two expressions show how the marginal tax rates of labor supply can be expressed as the marginal tax rate on labor income times the household-specific wage and how the marginal tax rate of savings can be expressed as the marginal tax rate of capital income times the interest rate. + As we show in Section [Optimality Conditions](https://pslmodels.github.io/OG-Core/content/theory/households.html#optimality-conditions) of the Households chapter of the `OG-Core` repository documentation, the derivative of total tax liability with respect to labor supply $\frac{\partial T_{s,t}}{n_{j,s,t}}$ and the derivative of total tax liability next period with respect to savings $\frac{\partial T_{s+1,t+1}}{b_{j,s+1,t+1}}$ show up in the household Euler equations for labor supply and savings , respectively, in the `OG-Core` documentation. It is valuable to be able to express those marginal tax rates, for which we have no data, as marginal tax rates for which we do have data. The following two expressions show how the marginal tax rates of labor supply can be expressed as the marginal tax rate on labor income times the household-specific wage and how the marginal tax rate of savings can be expressed as the marginal tax rate of capital income times the interest rate. ```{math} :label: EqMTRx_derive @@ -64,7 +71,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need `Tax-Calculator` starts with the underlying population microeconomic data, in which each observation is a filer with a population weight that renders the sample representative. It then processes the relevant income and demographic characteristics in order to calculate the tax liability of each individual, according to all the rich tax law of the United States tax code. `Tax-Calculator` can then calculate effective tax rates for all of these individuals, thereby creating a sample of how ETR's are related to other variables in our `OG-USA` model, such as total income $x + y$, labor income $x$, and capital income $y$. `Tax-Calculator` can also generate marginal tax rates by adding a dollar to each filer's income of a particular type and calculate how the filer's tax liability changes. This is a finite difference calculation of a derivative. - Figure {numref}`FigTaxCalcETRtotinc` shows a scatter plot of $ETR$'s for 43-year-olds in 2017 and unadjusted gross income $x + y$. It is clear that $ETR$ is positively related to income. It is also clear that a significant number of filers have a negative $ETR$. We will discuss in Section {ref}`SecTaxCalcFuncs` the functional form `OG-USA` uses to best capture the main characteristics of these ETR data. + {numref}`Figure %s ` shows a scatter plot of $ETR$'s for 43-year-olds in 2017 and unadjusted gross income $x + y$. It is clear that $ETR$ is positively related to income. It is also clear that a significant number of filers have a negative $ETR$. We will discuss in Section {ref}`SecTaxCalcFuncs` the functional form `OG-USA` uses to best capture the main characteristics of these ETR data. ```{figure} ./images/Compare_ETR_functions.png --- @@ -74,7 +81,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need Plot of estimated $ETR$ functions: $t=2017$ and $s=43$ under current law ``` - Figure {numref}`FigTaxCalc3Dtaxrates` shows 3D scatter plots of $ETR$, $MTRx$, and $MTRy$ (and a histogram of the data) with the labor income and capital income, separately, of each age-42 filer in 2017, generated by `Tax-Calculator`. This figure presents the main visual evidence for the functional form we use to fit tax functions to these data in Section {ref}`SecTaxCalcFuncs`. Figure {numref}`FigTaxCalc3Dtaxrates` presents strong evidence that the tax rate---$ETR$, $MTRx$, and $MTRy$---is most accurately modeled as a function of labor income and capital income, separately: $\tau(x,y)$. + {numref}`Figure %s ` shows 3D scatter plots of $ETR$, $MTRx$, and $MTRy$ (and a histogram of the data) with the labor income and capital income, separately, of each age-42 filer in 2017, generated by `Tax-Calculator`. This figure presents the main visual evidence for the functional form we use to fit tax functions to these data in Section {ref}`SecTaxCalcFuncs`. {numref}`Figure %s ` presents strong evidence that the tax rate---$ETR$, $MTRx$, and $MTRy$---is most accurately modeled as a function of labor income and capital income, separately: $\tau(x,y)$. ```{figure} ./images/Age42_2017_scatters.png @@ -88,7 +95,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need (SecTaxCalcFuncs)= ## Fitting Tax Functions - In looking at the 2D scatter plot on effective tax rates as a function of total income in Figure {numref}`FigTaxCalcETRtotinc` and the 3D scatter plots of $ETR$, $MTRx$, and $MTRy$ in Figure {numref}`FigTaxCalc3Dtaxrates`, it is clear that all of these rates exhibit negative exponential or logistic shape. This empirical regularity allows us to make an important and nonrestrictive assumption. We can fit parametric tax rate functions to these data that are constrained to be monotonically increasing in labor income and capital income. This assumption of monotonicity is computationally important as it preserves a convex budget set for each household, which is important for being able to solve many household lifetime problems over a large number of periods. + In looking at the 2D scatter plot on effective tax rates as a function of total income in {numref}`Figure %s ` and the 3D scatter plots of $ETR$, $MTRx$, and $MTRy$ in {numref}`Figure %s `, it is clear that all of these rates exhibit negative exponential or logistic shape. This empirical regularity allows us to make an important and nonrestrictive assumption. We can fit parametric tax rate functions to these data that are constrained to be monotonically increasing in labor income and capital income. This assumption of monotonicity is computationally important as it preserves a convex budget set for each household, which is important for being able to solve many household lifetime problems over a large number of periods. (SecTaxCalcFuncs_DEP)= @@ -113,7 +120,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need The respective $shift_x$ and $shift_y$ parameters in Equation {eq}`EqTaxCalcTaxFuncForm` are analogous to the additive constants in a Stone-Geary utility function. These constants ensure that the two sums $\tau(x) + shift_x$ and $\tau(y) + shift_y$ are both strictly positive. They allow for negative tax rates in the $\tau(\cdot)$ functions despite the requirement that the arguments inside the brackets be strictly positive. The general $shift$ parameter outside of the Cobb-Douglas brackets can then shift the tax rate function so that it can accommodate negative tax rates. The Cobb-Douglas share parameter $\phi\in[0,1]$ controls the shape of the function between the two univariate functions $\tau(x)$ and $\tau(y)$. - This functional form for tax rates delivers flexible parametric functions that can fit the tax rate data shown in Figure {numref}`FigTaxCalc3Dtaxrates` as well as a wide variety of policy reforms. Further, these functional forms are monotonically increasing in both labor income $x$ and capital income $y$. This characteristic of monotonicity in $x$ and $y$ is essential for guaranteeing convex budget sets and thus uniqueness of solutions to the household Euler equations. The assumption of monotonicity does not appear to be a strong one when viewing the the tax rate data shown in Figure {numref}`FigTaxCalc3Dtaxrates`. While it does limit the potential tax systems to which one could apply our methodology, tax policies that do not satisfy this assumption would result in non-convex budget sets and thus require non-standard DGE model solutions methods and would not guarantee a unique equilibrium. The 12 parameters of our tax rate functional form from {eq}`EqTaxCalcTaxFuncForm` are summarized in {numref}`TabTaxCalcTfuncParams`. + This functional form for tax rates delivers flexible parametric functions that can fit the tax rate data shown in {numref}`Figure %s ` as well as a wide variety of policy reforms. Further, these functional forms are monotonically increasing in both labor income $x$ and capital income $y$. This characteristic of monotonicity in $x$ and $y$ is essential for guaranteeing convex budget sets and thus uniqueness of solutions to the household Euler equations. The assumption of monotonicity does not appear to be a strong one when viewing the the tax rate data shown in {numref}`Figure %s `. While it does limit the potential tax systems to which one could apply our methodology, tax policies that do not satisfy this assumption would result in non-convex budget sets and thus require non-standard DGE model solutions methods and would not guarantee a unique equilibrium. The 12 parameters of our tax rate functional form from {eq}`EqTaxCalcTaxFuncForm` are summarized in {numref}`TabTaxCalcTfuncParams`. ```{list-table} **Description of tax rate function $\tau(x,y)$ parameters.** :header-rows: 1 @@ -229,13 +236,13 @@ The second difficulty in modeling realistic tax and incentive detail is the need &\qquad\text{subject to}\quad A, B, C, D > 0 \quad\text{and}\quad \phi\in[0,1] ``` - where $\tau_{i}$ is the tax rate for observation $i$ from the microsimulation output, $\tau_{s,t}(x_i,y_i|\tilde{\boldsymbol{\theta}}_{s,t},\bar{\boldsymbol{\theta}}_{s,t})$ is the predicted tax rate for filing-unit $i$ with $x_{i}$ labor income and $y_{i}$ capital income given parameters $\boldsymbol{\theta}_{s,t}$, and $w_{i}$ is the CPS sampling weight of this observation. The number $N$ is the total number of observations from the microsimulation output for age $s$ and year $t$. Figure {numref}`FigTaxCalc3DvsPred` shows the typical fit of an estimated tax function $\tau_{s,t}\bigl(x,y|\hat{\boldsymbol{\theta}}_{s,t}\bigr)$ to the data. The data in Figure {numref}`FigTaxCalc3DvsPred` are the same age $s=42$ and year $t=2017$ as the data Figure {numref}`FigTaxCalc3Dtaxrates`. + where $\tau_{i}$ is the tax rate for observation $i$ from the microsimulation output, $\tau_{s,t}(x_i,y_i|\tilde{\boldsymbol{\theta}}_{s,t},\bar{\boldsymbol{\theta}}_{s,t})$ is the predicted tax rate for filing-unit $i$ with $x_{i}$ labor income and $y_{i}$ capital income given parameters $\boldsymbol{\theta}_{s,t}$, and $w_{i}$ is the CPS sampling weight of this observation. The number $N$ is the total number of observations from the microsimulation output for age $s$ and year $t$. {numref}`Figure %s ` shows the typical fit of an estimated tax function $\tau_{s,t}\bigl(x,y|\hat{\boldsymbol{\theta}}_{s,t}\bigr)$ to the data. The data in {numref}`Figure %s ` are the same age $s=42$ and year $t=2017$ as the data {numref}`Figure %s `. The underlying data can limit the number of tax functions that can be estimated. For example, we use the age of the primary filer from the PUF-CPS match to be equivalent to the age of the DGE model household. The DGE model we use allows for individuals up to age 100, however the data contain few primary filers with age above age 80. Because we cannot reliably estimate tax functions for $s>80$, we apply the tax function estimates for 80 year-olds to those with model ages 81 to 100. In the case certain ages below age 80 have too few observations to enable precise estimation of the model parameters, we use a linear interpolation method to find the values for those ages $21\leq s <80$ that cannot be precisely estimated. [^interpolation_note] - In `OG-USA`, we estimate the 12-parameter functional form {eq}`EqTaxCalcTaxFuncForm` using weighted nonlinear least squares to fit an effective tax rate function $(\tau^{etr}_{s,t})$, a marginal tax rate of labor income function $(\tau^{mtrx}_{s,t})$, and a marginal tax rate of capital income function $(\tau^{mtry}_{s,t})$ for each age $E+1\leq s\leq E+S$ and each of the first 10 years from the current period. [^param_note] That means we have to perform 2,400 estimations of 12 parameters each. Figure {numref}`FigTaxCalc3DvsPred` shows the predicted surfaces for $\tau^{etr}_{s=42,t=2017}$, $\tau^{mtrx}_{s=42,t=2017}$, and $\tau^{mtry}_{s=42,t=2017}$ along with the underlying scatter plot data from which those functions were estimated. {numref}`TabTaxCalcEst42` shows the estimated values of those functional forms. + In `OG-USA`, we estimate the 12-parameter functional form {eq}`EqTaxCalcTaxFuncForm` using weighted nonlinear least squares to fit an effective tax rate function $(\tau^{etr}_{s,t})$, a marginal tax rate of labor income function $(\tau^{mtrx}_{s,t})$, and a marginal tax rate of capital income function $(\tau^{mtry}_{s,t})$ for each age $E+1\leq s\leq E+S$ and each of the first 10 years from the current period. [^param_note] That means we have to perform 2,400 estimations of 12 parameters each. {numref}`Figure %s ` shows the predicted surfaces for $\tau^{etr}_{s=42,t=2017}$, $\tau^{mtrx}_{s=42,t=2017}$, and $\tau^{mtry}_{s=42,t=2017}$ along with the underlying scatter plot data from which those functions were estimated. {numref}`TabTaxCalcEst42` shows the estimated values of those functional forms. - The full set of estimated values are calculated in the [`OG-USA/ogusa/txfunc.py`](https://github.com/open-source-economics/OG-USA/blob/master/ogusa/txfunc.py) module in the `OG-USA` repository. And the estimated values are stored in the [`TxFuncEst_baseline.pkl`](https://github.com/open-source-economics/OG-USA/blob/master/TxFuncEst_baseline.pkl) file. + The full set of estimated values are calculated using the [`get_tax_function_parameters`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/calibrate.py#L82) method of the [`Calibration`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/calibrate.py#L20) class of the [`OG-USA/ogusa/calibrate.py`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/calibrate.py#L20) module. And the estimated baseline values are stored in the [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/ogusa_default_parameters.json) file. (SecTaxCalcFuncs_Alt)= @@ -283,7 +290,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need However, this distribution function $\eta_{j,s,t}$ could also be modified to more accurately reflect the way transfers are distributed in the United States. -[^taxcalc_note]:`Tax-Calculator` is available through an open source repository [https://github.com/PSLmodels/Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator) as well as through a web application [Tax-Brain](https://compute.studio/PSLmodels/Tax-Brain/), hosted by [Compute.Studio](https://about.compute.studio/). Documentation for `Tax-Calculator` is available at [https://pslmodels.github.io/Tax-Calculator/](https://pslmodels.github.io/Tax-Calculator/). +[^taxcalc_note]:`Tax-Calculator` is available through an open source repository [https://github.com/PSLmodels/Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator) as well as through a web application [Tax-Brain](https://compute.studio/PSLmodels/Tax-Brain/), hosted by [Compute.Studio](https://about.compute.studio/). Documentation for `Tax-Calculator` is available at [https://taxcalc.pslmodels.org/](https://taxcalc.pslmodels.org/). [^interpolation_note]: We use two criterion to determine whether the function should be interpolated. First, we require a minimum number of observations of filers of that age and in that tax year. Second, we require that that sum of squared errors meet a predefined threshold. diff --git a/docs/book/content/citations.md b/docs/book/content/citations.md index 65edb5e1..0edc8836 100644 --- a/docs/book/content/citations.md +++ b/docs/book/content/citations.md @@ -1,5 +1,5 @@ # Citations and use cases of OG-USA -```{bibliography} ../../../citations.bib +```{bibliography} ../citations.bib :all : ``` diff --git a/docs/book/content/contributing/contributor_guide.md b/docs/book/content/contributing/contributor_guide.md index ed15c3c3..57536144 100644 --- a/docs/book/content/contributing/contributor_guide.md +++ b/docs/book/content/contributing/contributor_guide.md @@ -27,10 +27,10 @@ If you have already completed the {ref}`Sec_SetupPython` and {ref}`Sec_SetupGit` 5. From your command line, navigate to the directory on your computer where you would like your local repo to live. -6. Create a local repo by entering at the command line the text after the $.[^commandline_note] This step creates a directory called `OG-USA` in the directory that you specified in the prior step: +6. Create a local repo by entering at the command line the text, shown in the code blocks below after the `$` symbol.[^commandline_note] This step creates a directory called `OG-USA` in the directory that you specified in the prior step: ``` - git clone https://github.com/[github-username]/OG-USA.git + $ git clone https://github.com/[github-username]/OG-USA.git ``` 7. From your command line or terminal, navigate to your local `OG-USA` directory. @@ -39,11 +39,12 @@ If you have already completed the {ref}`Sec_SetupPython` and {ref}`Sec_SetupGit` ``` $ cd OG-USA - OG-USA$ git remote add upstream https://github.com/open-source-economics/OG-USA.git + OG-USA$ git remote add upstream https://github.com/PSLmodels/OG-USA.git ``` -9. Create a conda environment with all of the necessary packages to - execute the source code: +9. Create a conda environment with all of the necessary packages to execute the source code. +The process of creating the `ogusa-dev` conda environment can take more than 20 minutes. +The pip install of the `OG-Core` dependency from GitHub takes most of the time. ``` OG-USA$ conda env create @@ -56,6 +57,12 @@ If you have already completed the {ref}`Sec_SetupPython` and {ref}`Sec_SetupGit` OG-USA$ conda activate ogusa-dev ``` +11. Once the environment is activated, install the `ogusa` package in the `ogusa-dev` environment with all its modules by executing the following `pip install` command. + + ``` + (ogusa-dev) OG-USA$ pip install -e . + ``` + If you have made it this far, you've successfully made a remote copy (a fork) of the central `OG-USA` repo. That remote repo is hosted on GitHub.com at [https://github.com/PSLmodels/OG-USA](https://github.com/PSLmodels/OG-USA). You have also created a local repo (a [clone](https://help.github.com/articles/github-glossary/#clone)) that lives on your machine and only you can see; you will make your changes to @@ -86,19 +93,19 @@ The following text describes a typical workflow for changing `OG-USA`. Different workflows may be necessary in some situations, in which case other contributors are here to help. -1. Before you edit the OG-USA source code on your machine, +1. Before you edit the `OG-USA` source code on your machine, make sure you have the latest version of the central OG-USA repository by executing the following **four** Git commands: a. Tell Git to switch to the master branch in your local repo. - Navigate to your local OG-USA directory and enter the + Navigate to your local `OG-USA` directory and enter the following text at the command line: ``` OG-USA$ git checkout master ``` - b. Download all of the content from the central OG-USA repo: + b. Download all of the content from the central `OG-USA` repo: ``` OG-USA$ git fetch upstream ``` @@ -162,6 +169,6 @@ situations, in which case other contributors are here to help. (Sec_ContribFootnotes)= ## Footnotes -[^recent_python]:The most recent version of Python from Anaconda is Python 3.8. `OG-USA` is currently tested to run on Python 3.7 through 3.9. +[^recent_python]:The most recent version of Python from Anaconda is Python 3.9. `OG-USA` is currently tested to run on Python 3.8 and 3.9. [^commandline_note]:The dollar sign is the end of the command prompt on a Mac. If you are using the Windows operating system, this is usually the right angle bracket (>). No matter the symbol, you don't need to type it (or anything to its left, which shows the current working directory) at the command line before you enter a command; the prompt symbol and preceding characters should already be there. diff --git a/docs/book/content/intro/intro.md b/docs/book/content/intro/intro.md index e518f677..397202f1 100644 --- a/docs/book/content/intro/intro.md +++ b/docs/book/content/intro/intro.md @@ -1,10 +1,10 @@ (Chap_Intro)= -# OG-USA-Calibration +# OG-USA -`OG-USA-Calibration` is a package that provides code and data to calibrate an overlapping-generations (OG) model, `OG-MOD`, to the economy of the United States (USA). Together, `OG-MOD` + `OG-USA-Calibration` make the `OG-USA` model that allows for dynamic general equilibrium analysis of federal fiscal policy in the United States. The model output focuses changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. This documentation of the `OG-USA-Calibration` package contains the following major sections, which are regularly updated. +`OG-USA` is a package that provides code and data to calibrate an overlapping-generations (OG) model to the economy of the United States (USA). `OG-USA` uses as a dependency the [`OG-Core`](https://pslmodels.github.io/OG-Core/) package, which contains the core theory and logic of a general OG model. The `OG-USA` calibration package and the `OG-Core` theory and logic make the model that allows for dynamic general equilibrium analysis of federal fiscal policy in the United States. The model output focuses on changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. This documentation of the `OG-USA` package contains the following major sections, which are regularly updated. -* Contributing to `OG-USA-Calibration` -* `OG-USA-Calibration` API +* Contributing to `OG-USA` +* `OG-USA` API * Calibration * References * Citations of `OG-USA` @@ -13,13 +13,13 @@ (Sec_CoreMaintainers)= ## Core Maintainers -[Jason DeBacker](https://www.jasondebacker.com/) (GitHub handle [@jdebacker](https://github.com/jdebacker)) and [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle [@rickecon](https://github.com/rickecon)) are the core maintainers of `OG-USA-Calibration`. If you have questions about or contributions to the model or repository, please submit a GitHub "Issue" described in the {ref}`Sec_GitHubIssue` subsection or "Pull Request" as described in the {ref}`Sec_GitHubPR` subsection of the {ref}`Sec_Workflow` section of the `OG-USA-Calibration` {ref}`Chap_ContribGuide`. +[Jason DeBacker](https://www.jasondebacker.com/) (GitHub handle [@jdebacker](https://github.com/jdebacker)) and [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle [@rickecon](https://github.com/rickecon)) are the core maintainers of `OG-USA`. If you have questions about or contributions to the model or repository, please submit a GitHub "Issue" described in the {ref}`Sec_GitHubIssue` subsection or "Pull Request" as described in the {ref}`Sec_GitHubPR` subsection of the {ref}`Sec_Workflow` section of the `OG-USA` {ref}`Chap_ContribGuide`. (Sec_Disclaimer)= ## Disclaimer -The model is continuously under development. Users will be notified through [closed PR threads](https://github.com/PSLmodels/OG-USA-Calibration/pulls?q=is%3Apr+is%3Aclosed) and through the [release notes](https://github.com/PSLmodels/OG-USA-Calibration/releases) what changes have been implemented. The package will have released versions, which will be checked against existing code prior to release. Stay tuned for an upcoming release! +The model is continuously under development. Users will be notified through [closed PR threads](https://github.com/PSLmodels/OG-USA/pulls?q=is%3Apr+is%3Aclosed) and through the [release notes](https://github.com/PSLmodels/OG-USA/releases) what changes have been implemented. The package will have released versions, which will be checked against existing code prior to release. Stay tuned for an upcoming release! (Sec_CitingOGUSA)= diff --git a/environment.yml b/environment.yml index 433e506a..e603671b 100644 --- a/environment.yml +++ b/environment.yml @@ -8,7 +8,7 @@ dependencies: - mkl>=2020.2 - psutil - scipy>=1.5.0 -- pandas>=1.0.5 +- pandas>=1.2.5 - matplotlib - taxcalc>=3.0.0 - dask==2.30.0 @@ -16,7 +16,8 @@ dependencies: - distributed==2.30.1 - paramtools>=0.15.0 - openpyxl -- sphinx>=3.1.2 +- sphinx>=3.5.4 +- sphinx-book-theme>=0.1.3 - pip - pytest>=6.0 - pytest-pep8 @@ -31,7 +32,7 @@ dependencies: - rpy2 - black - pip: - - jupyter-book>=0.8.0 + - jupyter-book>=0.9.1 - cs-kit - cs2tc - pandas-datareader diff --git a/ogusa/calibrate.py b/ogusa/calibrate.py index 107a53ad..f5056407 100644 --- a/ogusa/calibrate.py +++ b/ogusa/calibrate.py @@ -93,14 +93,17 @@ def get_tax_function_parameters( """ Reads pickle file of tax function parameters or estimates the parameters from microsimulation model output. + Args: client (Dask client object): client run_micro (bool): whether to estimate parameters from microsimulation model tax_func_path (string): path where find or save tax function parameter estimates + Returns: None + """ # set paths if none given if tax_func_path is None: @@ -297,13 +300,16 @@ def read_tax_func_estimate(self, p, tax_func_path): """ This function reads in tax function parameters from pickle files. + Args: tax_func_path (str): path to pickle with tax function parameter estimates + Returns: dict_params (dict): dictionary containing arrays of tax function parameters run_micro (bool): whether to estimate tax function parameters + """ flag = 0 if os.path.exists(tax_func_path): diff --git a/ogusa/estimate_beta_j.py b/ogusa/estimate_beta_j.py index 1cb16fc0..f4e0d10e 100644 --- a/ogusa/estimate_beta_j.py +++ b/ogusa/estimate_beta_j.py @@ -26,11 +26,11 @@ def beta_estimate( distribution. Args: - beta_initial_guesses (array-like): array of initial guesses for the - beta_j parameters - og_spec (dict): any updates to default model parameters - two_step (boolean): whether to use a two-step estimator - client (Dask Client object): dask client for multiprocessing + beta_initial_guesses (array-like): array of initial guesses for the + beta_j parameters + og_spec (dict): any updates to default model parameters + two_step (boolean): whether to use a two-step estimator + client (Dask Client object): dask client for multiprocessing Returns: beta_hat (array-like): estimates of the beta_j @@ -108,12 +108,12 @@ def minstat(beta_guesses, *args): between the model and data moments. Args: - beta_guesses (array-like): a vector of length J with the betas - args (tuple): length 6 tuple, variables needed for minimizer + beta_guesses (array-like): a vector of length J with the betas + args (tuple): length 6 tuple, variables needed for minimizer Returns: - distance (scalar): weighted, squared deviation between data and - model moments + distance (scalar): weighted, squared deviation between data and + model moments """ # unpack args tuple @@ -146,8 +146,8 @@ def calc_moments(ss_output, p): to the data moments used for estimation. Args: - ss_output = dictionary, variables from SS of model - p (OG-USA Specifications object): model parameters + ss_output = dictionary, variables from SS of model + p (OG-USA Specifications object): model parameters Returns: model_moments (array-like): Array of model moments diff --git a/ogusa/get_micro_data.py b/ogusa/get_micro_data.py index 398e1270..40c43946 100644 --- a/ogusa/get_micro_data.py +++ b/ogusa/get_micro_data.py @@ -46,7 +46,7 @@ def get_calculator( in the Tax-Calculator project) Returns: - calc1 (Tax-Calculator Calculator object): Calulator object with + calc1 (Tax-Calculator Calculator object): Calculator object with current_year equal to calculator_start_year """ diff --git a/ogusa/income.py b/ogusa/income.py index 1d263700..e7043579 100644 --- a/ogusa/income.py +++ b/ogusa/income.py @@ -1,10 +1,9 @@ """ ------------------------------------------------------------------------- +----------------------------------------------------------------- Functions for created the matrix of ability levels, e. This can only be used for looking at the 25, 50, 70, 80, 90, 99, and 100th percentiles, as it uses fitted polynomials to those percentiles. -For a more generic version, see income_nopoly.py. ------------------------------------------------------------------------- +----------------------------------------------------------------- """ import numpy as np import scipy.optimize as opt @@ -30,7 +29,7 @@ def arctan_func(xvals, a, b, c): b (scalar): curvature parameter for arctan function c (scalar): shift parameter for arctan function - RETURNS: + Returns: yvals (Numpy array): predicted values (output) of arctan function @@ -54,7 +53,7 @@ def arctan_deriv_func(xvals, a, b, c): b (scalar): curvature parameter for arctan function c (scalar): shift parameter for arctan function - RETURNS: + Returns: yvals (Numpy array): predicted values (output) of arctan derivative function