diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..f8ae41c --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,10 @@ +Thanks for filing an issue. Please consider including the following information in your issue. This will help us efficiently respond to the issue and incorporate its valuable components into the repository. Please delete this paragraph, and feel free to include any of the following content that you think is relevant. + +# Clear and concise title +Please give this issue a clear and concise title that directly references the key point in your issue. + +# Problem or Error +Please characterize the problem concisely and precisely. You may want to include error message output, other terminal output, your environment characteristics, and a way to replicate the issue. Let us know what solutions you have tried. You may also want to include a minimal reproducible example (MRE; see [this Stackoverflow tutorial](https://stackoverflow.com/help/minimal-reproducible-example) and this [Wikipedia page](https://en.wikipedia.org/wiki/Minimal_reproducible_example)). These types of examples are referred to in other coding cotexts as "minimal,complete, and verifiable example (MCVE)", "minimal workable example (MWE)", "reprex", and "short, self-contained correct example (SSCCE)". + +# Question +Please ask the question with clear context and any potential answer directions you can think of. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..090ffb4 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,7 @@ +Thanks for contributing! Please remove any top-level sections that do not apply to your changes. + +- [ ] `make documentation`, `make format`, and `make test` have been run locally on my machine. + +## What's changed + +Description of the changes here. Link any issues this PR fixes. diff --git a/.github/workflows/build_and_test.yml b/.github/workflows/build_and_test.yml new file mode 100644 index 0000000..1dc5cc2 --- /dev/null +++ b/.github/workflows/build_and_test.yml @@ -0,0 +1,47 @@ +name: Build and test [Python 3.10, 3.11] + +on: [push, pull_request] + +jobs: + build: + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + python-version: ["3.10", "3.11"] + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + persist-credentials: false + + - name: Setup Miniconda using Python ${{ matrix.python-version }} + uses: conda-incubator/setup-miniconda@v2 + with: + miniforge-variant: Mambaforge + auto-update-conda: true + activate-environment: compmethods-dev + environment-file: environment.yml + python-version: ${{ matrix.python-version }} + auto-activate-base: false + + - name: Build + shell: bash -l {0} + run: | + pip install -e . + pip install pytest-cov + pip install pytest-pycodestyle + - name: Test + shell: bash -l {0} + working-directory: ./ + run: | + pytest -m 'not local' --cov=./ --cov-report=xml + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v3 + with: + files: ./coverage.xml + flags: unittests + name: codecov-umbrella + fail_ci_if_error: true + verbose: true diff --git a/.github/workflows/check_format.yml b/.github/workflows/check_format.yml new file mode 100644 index 0000000..1176d48 --- /dev/null +++ b/.github/workflows/check_format.yml @@ -0,0 +1,15 @@ + +name: Check code formatting + +on: [push, pull_request] + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + - uses: psf/black@stable + with: + options: "-l 79 --check" + src: "." diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml new file mode 100644 index 0000000..c46aeb1 --- /dev/null +++ b/.github/workflows/deploy_docs.yml @@ -0,0 +1,38 @@ +name: Build and Deploy Jupyter Book documentation +on: + push: + branches: + - main +jobs: + build-and-deploy: + if: github.repository == 'OpenSourceEcon/CompMethods' + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + persist-credentials: false + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v2 + with: + miniforge-variant: Mambaforge + activate-environment: compmethods-dev + environment-file: environment.yml + python-version: "3.10" + auto-activate-base: false + + - name: Build # Build Jupyter Book + shell: bash -l {0} + run: | + pip install -e . + python -m ipykernel install --user --name=compmethods-dev + cd docs + jb build ./book + + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages # The branch the action should deploy to. + FOLDER: docs/book/_build/html # The folder the action should deploy. diff --git a/.github/workflows/docs_check.yml b/.github/workflows/docs_check.yml new file mode 100644 index 0000000..27a22a1 --- /dev/null +++ b/.github/workflows/docs_check.yml @@ -0,0 +1,28 @@ +name: Check that docs build +on: [push, pull_request] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + persist-credentials: false + + - name: Setup Miniconda + uses: conda-incubator/setup-miniconda@v2 + with: + miniforge-variant: Mambaforge + activate-environment: compmethods-dev + environment-file: environment.yml + python-version: "3.10" + auto-activate-base: false + + - name: Build # Build Jupyter Book + shell: bash -l {0} + run: | + pip install -e . + python -m ipykernel install --user --name=compmethods-dev + cd docs + jb build ./book diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2be6cf3 --- /dev/null +++ b/.gitignore @@ -0,0 +1,42 @@ +*.pyc +MANIFEST +build/* +dist/* +*.aux +*.bbl +*.blg +*.fdb_latexmk +*.idx +*.ilg +*.ind +*.lof +*.log +*.lot +*.out +*.pdfsync +*.synctex.gz +*.toc +*.swp +*.asv +*.nav +*.snm +*.gz +*.bib.bak +*.fls +*.m~ +*.sublime* +.DS_Store +*puf.csv +*/OUTPUT/* +*/__pycache__/* +*.coverage* +*.pytest* +Icon? +.ipynb_checkpoints/* + +# Built Jupyter-book documentation +docs/book/_build + +# Backup docs +pdfs/* + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9078b2c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.0.0] - 2023-09-28 17:00:00 + +### Added + +- Created CompMethods repository at GitHub.com/OpenSourceEcon/CompMethods diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..2ffce9b --- /dev/null +++ b/Makefile @@ -0,0 +1,16 @@ +format: + black . -l 79 + linecheck . --fix +install: + pip install -e . +test: + pytest -m 'not local' +documentation: + jupyter-book clean docs/book + jupyter-book build docs/book +changelog: + build-changelog changelog.yaml --output changelog.yaml --update-last-date --start-from 0.0.0 --append-file changelog_entry.yaml + build-changelog changelog.yaml --org OpenSourceEcon --repo CompMeths --output CHANGELOG.md --template .github/changelog_template.md + bump-version changelog.yaml setup.py + rm changelog_entry.yaml || true + touch changelog_entry.yaml diff --git a/README.md b/README.md index c806c4d..f990781 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,24 @@ -# CompMethods -"Computational Methods for Economists using Python", by Richard W. Evans. Tutorials and executable code in Python for the most commonly used computational methods in economics. +# *Computational Methods for Economists using Python*, by Richard W. Evans + +| | | +| --- | --- | +| Org | [![OSE Lab cataloged](https://img.shields.io/badge/OSE%20Lab-catalogued-critical)](https://github.com/OpenSourceEcon) [![OS License: AGPL-3.0](https://img.shields.io/badge/OS%20License-AGPL%203.0-yellow)](https://github.com/OpenSourceEcon/CompMethods/blob/main/LICENSE) | +| Package | [![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-31013/) [![PyPI Latest Release](https://img.shields.io/pypi/v/compmethods.svg)](https://pypi.org/project/compmethods/) [![PyPI Downloads](https://img.shields.io/pypi/dm/compmethods.svg?label=PyPI%20downloads)](https://pypi.org/project/compmethods/) | +| Testing | ![example event parameter](https://github.com/OpenSourceEcon/CompMethods/actions/workflows/build_and_test.yml/badge.svg?branch=main) ![example event parameter](https://github.com/OpenSource/CompMethods/actions/workflows/deploy_docs.yml/badge.svg?branch=main) ![example event parameter](https://github.com/OpenSourceEcon/CompMethods/actions/workflows/check_format.yml/badge.svg?branch=main) [![Codecov](https://codecov.io/gh/OpenSourceEcon/CompMethods/branch/main/graph/badge.svg)](https://codecov.io/gh/OpenSourceEcon/compmethods) | + +This repository contains the source material, code, and data for the book, [*Computational Methods for Economists using Python*](https://opensourceecon.github.io/CompMethods/), by Richard W. Evans (2023). This book is freely available online as an executable Jupyter Book at [url to book](https://opensourceecon.github.io/CompMethods/). + +The materials for the book are constantly being updated. The version number listed in the [Releases](https://github.com/OpenSourceEcon/CompMethods/releases) section of the repository tracks the updates, as well as the [`CHANGELOG.md`](CHANGELOG.md) file. + +As an open executable book project, this book is happy to receive, address, and incorporate collaborative additions, corrections, suggestions, and questions. Please see the [Contributor Guide]() in the book for how to best collaborate with the project. + +[Richard W. Evans, Phd](https://sites.google.com/site/rickecon) ([@rickecon](https://github.com/rickecon)) is the author of the book and the core maintainer of this repository. + +## Citing this book +Please use the following citation form for this book. + +General citation to the book: +* Evans, Richard W., *Computational Methods for Economists using Python*, Open access Jupyter Book, v#.#.#, 2023, https://opensourceecon.github.io/CompMethods/. + +Citation to a chapter in the book: +* Evans, Richard W., "[insert chapter name]", in *Computational Methods for Economists using Python*, Open access Jupyter Book, v#.#.#, 2023, https://opensourceecon.github.io/CompMethods/[chapter path]. diff --git a/changelog.yaml b/changelog.yaml new file mode 100644 index 0000000..a0b363c --- /dev/null +++ b/changelog.yaml @@ -0,0 +1,5 @@ +- changes: + added: + - Created CompMethods repository at GitHub.com/OpenSourceEcon/CompMethods + date: 2023-09-28 17:00:00 + version: 0.0.0 diff --git a/code/placeholder.txt b/code/placeholder.txt new file mode 100644 index 0000000..eed293e --- /dev/null +++ b/code/placeholder.txt @@ -0,0 +1 @@ +placeholder.txt diff --git a/data/placeholder.txt b/data/placeholder.txt new file mode 100644 index 0000000..7045290 --- /dev/null +++ b/data/placeholder.txt @@ -0,0 +1 @@ +Put data here diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/CompMethodsLogo.png b/docs/CompMethodsLogo.png new file mode 100644 index 0000000..4b33069 Binary files /dev/null and b/docs/CompMethodsLogo.png differ diff --git a/docs/CompMethodsLogo_gitfig.png b/docs/CompMethodsLogo_gitfig.png new file mode 100644 index 0000000..070860f Binary files /dev/null and b/docs/CompMethodsLogo_gitfig.png differ diff --git a/docs/CompMethodsLogo_horizontal.png b/docs/CompMethodsLogo_horizontal.png new file mode 100644 index 0000000..5db2dbb Binary files /dev/null and b/docs/CompMethodsLogo_horizontal.png differ diff --git a/docs/CompMethodsLogo_vertical.png b/docs/CompMethodsLogo_vertical.png new file mode 100644 index 0000000..5237fa6 Binary files /dev/null and b/docs/CompMethodsLogo_vertical.png differ diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..994ab5e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Instructions for files in CompMethods/docs +The files in this directory `CompMethods/docs/` include images and all the files necessary for rendering the Jupyter Book documentation. One image [`CompMethodsLogo_gitfig.png`](docs/CompMethodsLogo_gitfig.png) is only used for the GitHub social preview image. GitHub suggests that this image should be 1280x640px for best display. The image we created [`CompMethodsLogo_horizontal.png`](docs/CompMethodsLogo_horizontal.png) is natively 759x267px. We do the following to resize the image. + +1. Open the image in Adobe Photoshop: **File** > **Open** +2. Open the **Image Size** dialogue: +3. Adjust the canvas size: **Image** > **Canvas Size**. Because the 759x276px image is relatively wider than the optimal 1280x640px GitHub size, we first adjust the canvas size. We have to add a little width and some moderate height. So here adjust the canvas width to 760px and then increase the height to half that size 380px. +4. Adjust the image size: **Image** > **Image Size**. Now adjust the image size to the GitHub optimal 1280x640px. The dimesions will be correct and nothing will be stretched. +5. Save the image as [`CompMethodsLogo_gitfig.png`](docs/CompMethodsLogo_gitfig.png). +6. Upload the image [`CompMethodsLogo_gitfig.png`](docs/CompMethodsLogo_gitfig.png) as the GitHub social preview image by clicking on the [**Settings**](https://github.com/OpenSourceEcon/CompMethods/settings) button in the upper-right of the main page of the repository and uploading the formatted image [`CompMethodsLogo_gitfig.png`](docs/CompMethodsLogo_gitfig.png) in the **Social preview** section. diff --git a/docs/book/CompMethods_references.bib b/docs/book/CompMethods_references.bib new file mode 100755 index 0000000..d1fb31f --- /dev/null +++ b/docs/book/CompMethods_references.bib @@ -0,0 +1,321 @@ +@ARTICLE{Armington:1969, + AUTHOR = {Paul S. Armington}, + TITLE = {A Theory of Demand for Products Distinguished by Place of Production}, + JOURNAL = {Staff Papers, International Monetary Fund}, + YEAR = {1969}, + volume = {16}, + number = {1}, + month = {March}, + pages = {159-178}, +} + +@INCOLLECTION{AuerbachKotlikoff:1983a, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff}, + TITLE = {National Savings, Economic Welfare, and the Structure of Taxation}, + BOOKTITLE = {Behavioral Simulation Methods in Tax Policy Analysis}, + PUBLISHER = {University of Chicago Press}, + YEAR = {1983}, + editor = {Martin Feldstein}, + type = {National Bureau of Economic Research Project Report}, + chapter = {Chap. 13}, + pages = {pp. 459-498}, +} + +@INCOLLECTION{AuerbachKotlikoff:1983b, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff}, + TITLE = {Investment versus Savings Incentives: The Size of the Bang for the Buck and the Potential for Self-financing Business Tax Cuts}, + BOOKTITLE = {The Economic Consequences of Government Deficits}, + PUBLISHER = {Kluwer-Nijhoff Publishing}, + YEAR = {1983}, + editor = {Lawrence. H. Meyer}, + series = {Economic Policy Conference Series}, + type = {Center for the Study of American Business}, + chapter = {Chap. 4}, + pages = {pp. 121-149}, +} + +@INCOLLECTION{AuerbachKotlikoff:1983c, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff}, + TITLE = {An Examination of Empirical Tests of {S}ocial {S}ecurity and Savings}, + BOOKTITLE = {Social Policy Evaluation: An Economic Perspective}, + PUBLISHER = {Academic Press}, + YEAR = {1983}, + editor = {Elhanan Helpman and Assaf Razin and Efraim Sadka}, + chapter = {Chap. 8}, + pages = {pp. 161-179}, +} + +@ARTICLE{AuerbachKotlikoff:1985, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff}, + TITLE = {Simulating Alternative {S}ocial {S}ecurity Responses to the Demographic Transition}, + JOURNAL = {National Tax Journal}, + YEAR = {1985}, + volume = {38}, + number = {2}, + month = {June}, + pages = {153-168}, +} + +@TECHREPORT{AuerbachEtAl:1981, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff and Jonathan Skinner}, + TITLE = {The Efficiency Gains from Dynamic Tax Reform}, + INSTITUTION = {National Bureau of Economic Research}, + YEAR = {1981}, + type = {NBER Working Paper}, + number = {819}, + month = {December}, +} + +@ARTICLE{AuerbachEtAl:1983, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff and Jonathan Skinner}, + TITLE = {The Efficiency Gains from Dynamic Tax Reform}, + JOURNAL = {International Economic Review}, + YEAR = {1983}, + volume = {24}, + number = {1}, + month = {February}, + pages = {81-100}, +} + +@BOOK{AuerbachKotlikoff:1987, + AUTHOR = {Alan J. Auerbach and Laurence J. Kotlikoff}, + TITLE = {Dynamic Fiscal Policy}, + PUBLISHER = {Cambridge University Press}, + YEAR = {1987}, +} + +@TECHREPORT{BenzellEtAl:2017, + AUTHOR = {Seth G. Benzell and Laurence J. Kotlikoff and Guillermo LaGarda}, + TITLE = {Simulating Business Cash Flow Taxation: An Illustration Based on the ``{B}etter {W}ay'' Corporate Tax Reform}, + INSTITUTION = {National Bureau of Economic Research}, + YEAR = {2017}, + type = {NBER Working Paper}, + number = {23675}, + month = {August}, +} + +@ARTICLE{BrummGrill:2014, + AUTHOR = {Johannes Brumm and Michael Grill}, + TITLE = {Computing Equilibria in Dynamic Models with Occasionally Binding Constraints}, + JOURNAL = {Journal of Economic Dynamics \& Control}, + YEAR = {2014}, + volume = {38}, + month = {January}, + pages = {142-160}, +} + +@TECHREPORT{BYUACME_PythonIntro, + AUTHOR = {BYU ACME}, + TITLE = {Introduction to Python}, + INSTITUTION = {Brigham Young University Applied and Computational Mathematics Emphasis}, + YEAR = {2021}, + type = {Open access lab}, + url = {https://acme.byu.edu/00000181-448a-d778-a18f-dfcae22f0001/intro-to-python}, +} + +@ARTICLE{CarrollEtAl:2017, + AUTHOR = {Christopher Carroll and Jiri Slacalek and Kiichi Tokuoka and Matthew N. White}, + TITLE = {The Distribution of Wealth and the Marginal Propensity to Consume}, + JOURNAL = {Quantitative Economics}, + YEAR = {2017}, + volume = {8}, + number = {3}, + month = {November}, + pages = {977-1020}, +} + +@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}, + JOURNAL = {Public Finance Review}, + YEAR = {2019}, + volume = {47}, + number = {2}, + month = {March}, + pages = {207-275}, +} + +@ARTICLE{EilersMarx:1996, + AUTHOR = {Paul H. C. Eilers and Brian D. Marx}, + TITLE = {Flexible Smoothing with B-splines and Penalties}, + JOURNAL = {Statistical Science}, + YEAR = {1996}, + volume = {11}, + number = {2}, + month = {May}, + pages = {89-121}, +} + +@ARTICLE{Eilers:2003, + AUTHOR = {Paul H. C. Eilers}, + TITLE = {A Perfect Smoother}, + JOURNAL = {Anals of Chemistry}, + YEAR = {2003}, + volume = {75}, + number = {14}, + month = {July}, + pages = {3631-3636}, +} + +@ARTICLE{Eilers:2005, + AUTHOR = {Paul H. C. Eilers}, + TITLE = {Unimodal Smoothing}, + JOURNAL = {Joural of Chemometrics}, + YEAR = {2005}, + volume = {19}, + number = {?}, + month = {?}, + pages = {317-328}, +} + +@ARTICLE{EvansPhillips:2014, + AUTHOR = {Richard W. Evans and Kerk L. Phillips}, + TITLE = {{OLG} Life Cycle Model Transition Paths: Alternate Model Forecast Method}, + JOURNAL = {Computational Economics}, + YEAR = {2014}, + volume = {43}, + number = {1}, + month = {January}, + pages = {105-131}, +} + +@ARTICLE{EvansPhillips:2017, + AUTHOR = {Richard W. Evans and Kerk L. Phillips}, + TITLE = {Advantages of an Ellipse when Modeling Leisure Utility}, + JOURNAL = {Computational Economics}, + YEAR = {2017}, + volume = {51}, + number = {3}, + month = {March}, + pages = {513-533}, +} + +@ARTICLE{Geary:1950, + AUTHOR = {Roy C. Geary}, + TITLE = {A Note on `A Constant-Utility Index of the Cost of Living'}, + JOURNAL = {Review of Economics Studies}, + YEAR = {1950-51}, + volume = {18}, + number = {1}, + pages = {65-66}, +} + +@ARTICLE{GitWiki2020, + AUTHOR = {{Wikipedia Contributors}}, + TITLE = {"{G}it"}, + JOURNAL = {{W}ikipedia{,} The Free Encyclopedia}, + YEAR = {2020}, + note = {[Online; accessed 19-August-2020]}, + url = {https://en.wikipedia.org/wiki/Git}, +} + +@ARTICLE{GitIDE2020, + AUTHOR = {{Wikipedia Contributors}}, + TITLE = {"{I}ntegrated development environment"}, + JOURNAL = {{W}ikipedia{,} The Free Encyclopedia}, + YEAR = {2020}, + note = {[Online; accessed 3-August-2020]}, + url = {https://en.wikipedia.org/wiki/Integrated_development_environment}, +} + +@Article{GouveiaStrauss:1994, + author={Miguel Gouveia and Robert P. Strauss}, + title={Effective Federal Individual Tax Functions: An Exploratory Empirical Analysis}, + journal={National Tax Journal}, + year={1994}, + volume={47}, + number={2}, + pages={317-39}, + month={June}, +} + +@ARTICLE{HurstEtAl:2014, + title = {Are Household Surveys Like Tax Forms? Evidence from Income Underreporting of the Self-Employed}, + author = {Hurst, Erik and Li, Geng and Pugsley, Benjamin}, + year = {2014}, + journal = {The Review of Economics and Statistics}, + volume = {96}, + number = {1}, + pages = {19-33}, + url = {https://EconPapers.repec.org/RePEc:tpr:restat:v:96:y:2014:i:1:p:19-33} +} + +@TECHREPORT{MoorePecoraro:2021, + AUTHOR = {Rachel Moore and Brandon Pecoraro}, + TITLE = {Quantitative Analysis of a Wealth Tax in the United States: Exclusions, Evasion, and Expenditures}, + INSTITUTION = {University Library of Munich, Germany}, + YEAR = {2021}, + type = {MPRA Paper}, + number = {109120}, + address = {https://ideas.repec.org/p/pra/mprapa/109120.html}, +} + +@ARTICLE{Nishiyama:2015, + AUTHOR = {Shinichi Nishiyama}, + TITLE = {Fiscal Policy Effects in a Heterogeneous-agent {OLG} Economy with an Aging Population}, + JOURNAL = {Journal of Economic Dynamics and Control}, + YEAR = {2015}, + volume = {61}, + month = {December}, + pages = {114-132}, +} + +@ARTICLE{NishiyamaSmetters:2007, + Author = {Shinichi Nishiyama and Kent Smetters}, + Title = {Does {S}ocial {S}ecurity Privatization Produce Efficiency Gains?}, + Journal = {Quarterly Journal of Economics}, + Year = {2007}, + Volume = {122}, + Number = {4}, + Pages = {1677-1719}, + Month = {November}, +} + +@ARTICLE{Peterman:2016, + AUTHOR = {William B. Peterman}, + TITLE = {Reconciling Micro and Macro Estimates of the {F}risch Labor Supply Elasticity}, + JOURNAL = {Economic Inquiry}, + YEAR = {2016}, + volume = {54}, + number = {1}, + month = {January}, + pages = {100-120}, +} + +@ARTICLE{Solow:1956, + AUTHOR = {Robert M. Solow}, + TITLE = {A Contribution to the Theory of Economic Growth}, + JOURNAL = {Quarterly Journal of Economics}, + YEAR = {1956}, + volume = {70}, + number = {1}, + month = {February}, + pages = {65-94}, +} + +@BOOK{StokeyLucas1989, + AUTHOR = {Nancy L. Stokey and Robert E. {Lucas, Jr.} and Edward C. Prescott}, + TITLE = {Recursive Methods in Economic Dynamics}, + PUBLISHER = {Harvard University Press}, + YEAR = {1989}, +} + +@ARTICLE{Stone:1954, + AUTHOR = {Richard Stone}, + TITLE = {Linear Expenditure Systems and Demand Analysis: An Application to the Pattern of British Demand}, + JOURNAL = {The Economic Journal}, + YEAR = {1954}, + volume = {64}, + number = {255}, + month = {September}, + pages = {511-527}, +} + +@ARTICLE{Suzumura:1983, + Author = {Kotaro Suzumura}, + Journal = {Hitotsubashi Journal of Economics}, + Pages = {137-141}, + Title = {{P}erron-{F}robenius Theorem on Non-Negative Square Matrices: An Elementary Proof}, + Volume = {24}, + Year = {1983}, +} diff --git a/docs/book/CompMethods_references.md b/docs/book/CompMethods_references.md new file mode 100644 index 0000000..0ab7d6b --- /dev/null +++ b/docs/book/CompMethods_references.md @@ -0,0 +1,5 @@ +# References + +```{bibliography} CompMethods_references.bib +:style: alpha +``` diff --git a/docs/book/_config.yml b/docs/book/_config.yml new file mode 100644 index 0000000..7d20751 --- /dev/null +++ b/docs/book/_config.yml @@ -0,0 +1,107 @@ +#################################################### +# Computational Methods for Economists using Python, +# Jupyter Book documentation settings +#################################################### +title : Computational Methods for Economists using Python +author : Richard W. Evans +copyright : '2023' +logo : '..//CompMethodsLogo.png' + +#################################################### +# Execution settings +execute: + execute_notebooks: force + timeout: -1 + +####################################################################################### +# Parse and render settings +parse: + myst_enable_extensions: # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html + - amsmath + - colon_fence + # - deflist + - dollarmath + # - html_admonition + # - html_image + - linkify + # - replacements + # - smartquotes + - substitution + - tasklist + - html_image + myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links + myst_dmath_double_inline: true # Allow display math ($$) within an inline context + +#################################################### +# HTML-specific settings +html: + favicon : "..//favicon.ico" # A path to a favicon image + use_edit_page_button : false # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in + use_repository_button : true # Whether to add a link to your repository button + use_issues_button : true # Whether to add an "open an issue" button + use_multitoc_numbering : true # Continuous numbering across parts/chapters + extra_navbar : Powered by Jupyter Book # Will be displayed underneath the left navbar. + extra_footer : "" # Will be displayed underneath the footer. + google_analytics_id : "" # A GA id that can be used to track book views. + home_page_in_navbar : true # Whether to include your home page in the left Navigation Bar + # baseurl : "" # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/ + # analytics: + # comments: + # hypothesis : false + # utterances : false + # announcement : "" # A banner announcement at the top of the site. + +####################################################################################### +# LaTeX and BibTex settings +latex: + latex_engine : pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex' + use_jupyterbook_latex : true # use sphinx-jupyterbook-latex for pdf builds as default + +bibtex_bibfiles: + - CompMethods_references.bib +#################################################### +# Launch button settings +launch_buttons: + notebook_interface : 'classic' # The interface interactive links will activate ["classic", "jupyterlab"] + # binderhub_url : https://mybinder.org # The URL of the BinderHub (e.g., https://mybinder.org) + # jupyterhub_url : "" # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu) + # thebelab : false # Add a thebelab button to pages (requires the repository to run on Binder) + colab_url : "" # The URL of Google Colab (https://colab.research.google.com) + +####################################################################################### +# FiscalSim-US repository settings +repository: + url: https://github.com/OpenSourceEcon/CompMethods + branch: main + path_to_book: "docs/book" + +####################################################################################### +# Advanced and power-user settings +sphinx: + extra_extensions : ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', + 'alabaster'] # A list of extra extensions to load by Sphinx. + config : # key-value pairs to directly over-ride the Sphinx configuration + bibtex_reference_style: author_year + mathjax_path : https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + +####################################################################################### +# Advanced Sphinx settings +sphinx: + extra_extensions: ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', + 'sphinx.ext.viewcode', 'sphinx.ext.napoleon', + 'alabaster', 'sphinx_exercise'] # A list of extra extensions to load by Sphinx. + config: # key-value pairs to directly over-ride the Sphinx configuration + bibtex_reference_style: author_year + mathjax_path: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js + html_js_files: + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js + # html_theme: furo + pygments_style: default + extra_extensions: + - "sphinx.ext.autodoc" + - "sphinxarg.ext" + - "sphinx.ext.viewcode" + - "sphinx.ext.napoleon" + - "sphinx.ext.mathjax" + - "sphinx_exercise" diff --git a/docs/book/_toc.yml b/docs/book/_toc.yml new file mode 100644 index 0000000..6d649a0 --- /dev/null +++ b/docs/book/_toc.yml @@ -0,0 +1,41 @@ +format: jb-book +root: index +parts: + - caption: Contributor Guide + chapters: + - file: contrib/contributing + - caption: Coding in Python + chapters: + - file: python/intro + - file: python/StandardLibrary + - file: python/OOP + - file: python/NumPy + - file: python/Pandas + - file: python/Matplotlib + - file: python/SciPy + - file: python/DocStrings + - file: python/UnitTesting + - caption: Git and GitHub + chapters: + - file: git/intro + - caption: Basic Causal Inference + chapters: + - file: caus_inf/intro + - caption: Basic Machine Learning + chapters: + - file: basic_ml/intro + - caption: Neural Nets and Deep Learning + chapters: + - file: deep_learn/intro + - caption: Structural Estimation + chapters: + - file: struct_est/intro + - file: struct_est/GMM + - file: struct_est/SMM + - caption: Appendix + chapters: + - file: appendix/glossary + - file: appendix/intro + - caption: References + chapters: + - file: CompMethods_references diff --git a/docs/book/appendix/glossary.md b/docs/book/appendix/glossary.md new file mode 100644 index 0000000..a2aada0 --- /dev/null +++ b/docs/book/appendix/glossary.md @@ -0,0 +1,112 @@ +(chap_glossary)= +# Glossary + +```{glossary} +application programming interface (API) + An application programming interface or API is the medium, method, and rules through which a user interacts with software. The API includes a medium which can be a {term}`command line interface` on a specific {term}`local` terminal or a {term}`graphical user interface`. The API also defines the commands through which a user interacts with the software. + +benevolent dictator + TODO: Make *benevolent dictator* entry... + +Bitbucket + *Bitbucket* or [*Bitbucket.org*](https://bitbucket.org/) is a {term}`cloud` {term}`source code management service` platform designed to enable scalable, efficient, and secure version controlled collaboration by linking {term}`local` {term}`Git` version controlled software development by developers. + +Bitkeeper + TODO: Put Bitkeeper definition here... + +Box, Inc. + TODO: Box Inc. definition... University file sharing company... + +branch + TODO: define branch + +centralized version control system + A centralized version control system or CVCS is an approach to version control in which all the files in a {term}`repository` as well as the change history (content and timing) are located on a central {term}`remote` server. User's check out versions of files from the repository and check them back in, creating new change history on the central server. + +clone + Clone can be a verb or a noun in the context of {term}`Git` software. A clone is a {term}`local` copy of a {term}`remote` {term}`repository` with its entire Git {term}`distributed version control system` history. To *clone* a repository is to use the `git clone [repo path]` command to copy a remote repository to your local machine with the accompanying Git version control history. + +cloud + Cloud can be a descriptor or a noun. As a descriptor, cloud refers to computational resources, such as servers, that are accessed remotely via the internet. As a noun, remote computational resources and storage can be referred to generically as "the cloud". + +command line interface + TODO: A *command line interface* or CLI... + +commit + TODO: *Commit* can be a verb or a noun. Define commit... + +continuous integration + Continuous integration or continuous integration unit testing is... + +distributed version control system + A *distributed version control system* or DVCS is {term}`version control system` software on any computer, {term}`local` or {term}`remote`, that tracks the entire history of changes to a {term}`repository` and coordinates and organizes collaboration among multiple users. It is distributed in the sense that multiple {term}`clone`s of a single {term}`remote` repository have the same full history of that repository. + +Dropbox + TODO: define Dropbox + +fork + TODO: define fork + +Git + *Git* is {term}`open source` {term}`version control system` software with capability designed to also operate as {term}`distributed version control system` (DVCS) software that resides on your local computer and tracks changes and the history of changes to all the files in a directory or {term}`repository`. See the Git website [https://git-scm.com/](https://git-scm.com/) and the [Git Wikipedia entry](https://en.wikipedia.org/wiki/Git) {cite}`GitWiki2020` for more information. + +GitHub + *GitHub* or [*GitHub.com*](https://github.com/) is a {term}`cloud` {term}`source code management service` platform designed to enable scalable, efficient, and secure version controlled collaboration by linking {term}`local` {term}`Git` version controlled software development by users. *GitHub*'s main business footprint is hosting a collection of millions of version controlled code repositories. In addition to being a platform for {term}`distributed version control system` (DVCS), *GitHub*'s primary features include code review, project management, {term}`continuous integration` {term}`unit testing`, {term}`GitHub actions`, and associated web page (GitHub pages) and documentation hosting and deployment. + +GitHub actions + GitHub actions + +GitLab + TODO: define *GitLab*... + +Google Docs + TODO: define Google Docs + +Google Drive + TODO: define Google Drive + +graphical user interface + A graphical user interface or GUI... + +integrated development environment + Integrated development environment or IDE is a software application that comsolidates many of the functions of software development under one program. IDE's often include a code editor, object memory and identification, debugger, and build automation tools. (See [IDE Wikipedia entry](https://en.wikipedia.org/wiki/Integrated_development_environment) {cite}`GitIDE2020`.) + +Linux + TODO: write Linux description... + +local + *Local* is a descriptor that refers to files that reside or operations that are performed on a user's machine to which he or she has direct access without using the internet. + +local version control system + A *local version control system* or LVCS is the simplest and most common approach to VCS. LVCS stores all the changes to the files in a {term}`repository` locally on the user's machine as a series of changes or deltas in the files. This is the approach taken by Apple's Time Machine backup software as most software that includes an "undo" function. + +merge + TODO: create *merge* entry... + +OG-Core + *`OG-Core`* is an open source large scale overlapping generations macroeconomic model of fiscal policy. This model is general and is a dependency of country calibrations that use `OG-Core`, such as `OG-USA`. + +open source + *Open source* is a descriptor that is usually applied to software or computer code projects, but can also be applied to any project based upon or represented by digital files. An open source project is one in which the source code is freely available to be downloaded and used and in which collaboration, improvements, and changes to the code are encouraged. The free download and use (outward direction) aspect of *open source* is often emphasized. But the collaboration and improvement contribution (inward direction) aspect is at least as important. {term}`Git` and {term}`GitHub` have enabled efficient and scalable collaboration to a degree not seen in other collaborative workflows. + +pull request + TODO: define *pull request*... + +remote + *Remote* is a descriptor that refers to files that reside or operations that are carried out on a server to which a user has access using the internet. + +repository + A *repository* or "repo" is a directory containing files that are tracked by a version control system. A local repository resides on a local machine. A remote repository resides in the cloud. + +source code management service + A *source code management service* is a {term}`cloud` platform that hosts computer code files and provides either {term}`centralized version control system` (CVCS) or {term}`distributed version control system`. As the central hub of either CVCS or DVCS, the source code management service provides the platform and rules for distributed code collaboration. Leading examples are {term}`GitHub` and {term}`Bitbucket`. + +unit testing + Unit testing is... + +version control system + *Version control system* or version control software or VCS is software that records changes to a set of files, including the order in which the changes were made and the content of those changes, in such a way that previous versions can be recalled or restored. + +Visual Studio Code (VS Code) + *Visual Studio Code* or *VS Code* is an open source text editor maintained by Microsoft. +``` diff --git a/docs/book/appendix/intro.md b/docs/book/appendix/intro.md new file mode 100644 index 0000000..1a74772 --- /dev/null +++ b/docs/book/appendix/intro.md @@ -0,0 +1,10 @@ +(Chap_AppendixIntro)= +# Appendix + +Put Appendix intro here. + + +(SecAppendixIntroFootnotes)= +## Footnotes + + diff --git a/docs/book/basic_ml/intro.md b/docs/book/basic_ml/intro.md new file mode 100644 index 0000000..077b6c9 --- /dev/null +++ b/docs/book/basic_ml/intro.md @@ -0,0 +1,10 @@ +(Chap_BasicMLintro)= +# Basic Machine Learning + +Put basic machine learning intro here. + + +(SecBasicMLintroFootnotes)= +## Footnotes + + diff --git a/docs/book/caus_inf/intro.md b/docs/book/caus_inf/intro.md new file mode 100644 index 0000000..c34dc87 --- /dev/null +++ b/docs/book/caus_inf/intro.md @@ -0,0 +1,10 @@ +(Chap_CausInfIntro)= +# Basic Causal Inference + +Put basic causal inference intro here. + + +(SecCausInfIntroFootnotes)= +## Footnotes + + diff --git a/docs/book/contrib/contributing.md b/docs/book/contrib/contributing.md new file mode 100644 index 0000000..dbfdcc2 --- /dev/null +++ b/docs/book/contrib/contributing.md @@ -0,0 +1,54 @@ +(Chap_Contrib)= +# Contributor Guide + +This chapter details how to contribute to the *Computational Methods for Economists using Python* book and associated repository. The CompMethods project follows the [GitHub workflow](https://guides.github.com/introduction/flow/) and [semantic versioning protocol](http://semver.org/). + + +## Create an Issue + +If you have a suggestion, correction, or addition you want to contribute to the CompMethods project and content, a good first approach is to file an Issue in the repository by going to the [Issues page](https://github.com/OpenSourceEcon/CompMethods/issues) and selecting the green "[New issue](https://github.com/OpenSourceEcon/CompMethods/issues/new)" button. For a productive new issue, please include the following. +* Clear and concise issue title that directly references the key point in your issue +* Clear and concise description of your question, problem, or error +* Error traceback message output or other terminal output +* Include a [minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example) + + +## Pull requests + +This project follows the [GitHub Flow](https://guides.github.com/introduction/flow/). All code contributions are submitted via a [pull request](https://github.com/OpenSourceEcon/CompMethods/pulls) towards the `main` branch. Opening a Pull Request means you are submitting all of the lines of code you have changed in a branch of your fork of this repository that you want to be considered to be merged into the repository. Once a pull request is submitted, project maintainers will review your submission and may ask for changes and clarifications via the pull request message thread. Once the reviewers are satisfied with the submission, they will merge it into the repository and those changes will become part of the project. + +### Automatic testing + +This project uses GitHub Actions to run automatic tests to make sure that the documentation builds, that the code runs correctly, and that the code is formatted correctly. In your pull requests, you should signify that you have run these tests locally on your machine using the `compmethods-dev` conda environment and successfully running the `make documentation`, `make test`, and `make format` commands. These tests will run automatically in the cloud on every commit to every pull request, but it is helpful for you to successfully run those tests locally on your machine. + + +### Peer reviews + +All pull requests must be reviewed by someone else than their original author, with few exceptions of pull requests from the main model maintainers. To help reviewers, make sure to add to your PR a **clear text explanation** of your changes. In case of changes that break past functionality and connections, you **must** give details about what features were deprecated. You must also provide guidelines to help users adapt their code to be compatible with the new version of the package. + +## Project version tracking + +This project follows the [semantic versioning protocol](http://semver.org/). Any change impacts the version number, and the version number conveys API compatibility information **only**. + +Every pull request submitted to the main branch of the repository should update the `CHANGELOG.md` and `changelog.yaml` files as well as update the version number of the project in `setup.py`. These version updates to the version number and to the changelog file descriptions have the following structure and format: +```yaml +- bump: {major, minor, patch} + changes: + {added, removed, changed, fixed}: + - +``` + +### Patch bump (3rd digit update) + +- Typographical and stylistic updates. Small code and data updates. +- Update the third digit of the version number. Ex: Version number would move from 0.0.0 to 0.0.1. + +### Minor bump + +- Adding a new section, major data, or majore code example to the Jupyter Book +- Update the second digit of the version number. Ex: Version number would move from 0.0.0 to 0.1.0. + +### Major bump + +- Major update, refactor, or compatibility change. +- Update the first digit of the version number. Ex: Version number would move from 0.0.0 to 1.0.0. diff --git a/docs/book/deep_learn/intro.md b/docs/book/deep_learn/intro.md new file mode 100644 index 0000000..332a3d2 --- /dev/null +++ b/docs/book/deep_learn/intro.md @@ -0,0 +1,10 @@ +(Chap_DeepLearnIntro)= +# Neural Nets and Deep Learning + +Put neural nets and deep learning intro here. + + +(SecDeepLearnIntroFootnotes)= +## Footnotes + + diff --git a/docs/book/git/intro.md b/docs/book/git/intro.md new file mode 100644 index 0000000..b5e89e5 --- /dev/null +++ b/docs/book/git/intro.md @@ -0,0 +1,10 @@ +(Chap_GitIntro)= +# Git and GitHub + +Put Git and GitHub intro here. + + +(SecGitIntroFootnotes)= +## Footnotes + + diff --git a/docs/book/images/icon_GitHub.png b/docs/book/images/icon_GitHub.png new file mode 100644 index 0000000..041de4e Binary files /dev/null and b/docs/book/images/icon_GitHub.png differ diff --git a/docs/book/images/icon_background.png b/docs/book/images/icon_background.png new file mode 100644 index 0000000..afc638d Binary files /dev/null and b/docs/book/images/icon_background.png differ diff --git a/docs/book/images/icon_download.png b/docs/book/images/icon_download.png new file mode 100644 index 0000000..b129d5a Binary files /dev/null and b/docs/book/images/icon_download.png differ diff --git a/docs/book/images/icon_fullscreen.png b/docs/book/images/icon_fullscreen.png new file mode 100644 index 0000000..717ee90 Binary files /dev/null and b/docs/book/images/icon_fullscreen.png differ diff --git a/docs/book/images/icon_search.png b/docs/book/images/icon_search.png new file mode 100644 index 0000000..a1e9926 Binary files /dev/null and b/docs/book/images/icon_search.png differ diff --git a/docs/book/index.md b/docs/book/index.md new file mode 100644 index 0000000..af1ca91 --- /dev/null +++ b/docs/book/index.md @@ -0,0 +1,42 @@ +# Computational Methods for Economists using Python + +This site contains open access tutorial materials and exercises for learning and using modern computational methods used by economists and data scientists. These materials have been developed by [Richard W. Evans](https://sites.google.com/site/rickecon) since 2008 primarily through the following endeavors: +* (2008-2016) Assistant Professor, Department of Economics, Brigham Young University. Taught undergraduate courses in macroeconomics, international finance, advanced macroeconomics, computational methods. +* (2012-2016) Co-founder and co-director of the BYU Macroeconomics and Computational Laboratory. +* (2013-2016) Co-PI, National Science Foundation Grant for original development of Applied and Computational Math Emphasis (ACME) curriculum at Brigham Young University. +* (2013-present) National advisory board member for the Applied and Computational Math Emphasis (ACME), Brigham Young University. +* (2014-2018) Economist, Open Source Policy Center, American Enterprise Institute. +* (2016-present) Founder and Director, Open Source Economics Laboratory. +* (2016-2019) Fellow, Becker Friedman Institute, University of Chicago. +* (2016-2020) Senior Lecturer and Associate Director, Masters in Computational Social Science, University of Chicago. Taught graduate students data science, computational methods, structural estimation, overlapping generations models. +* (2016-present) President, Open Research Group, Inc. +* (2022-present) Senior Research Fellow and Director of Open Policy, Center for Growth and Opportunity at Utah State University. + +The core maintainer of this project is the following: +* [**Richard W. Evans**](https://sites.google.com/site/rickecon), Senior Research Fellow and Director of Open Policy, Center for Growth and Opportunity at Utah State University; President and Co-founder, Open Research Group, Inc. (GitHub handle: [@rickecon](https://github.com/rickecon)) + +We welcome collaboration on the maintenance and improvement of this tutorial. If you have changes you would like to see or errors that you find, please open [an issue](https://github.com/OpenSourceEcon/CompMethods/issues) in the GitHub repository or submit a [pull request](https://github.com/OpenSourceEcon/CompMethods/pulls). More details on how to collaborate with this project are the {ref}`Chap_Contrib` chapter. + + +## Tutorial site functionality +This site was created using the [Executable Books](https://executablebooks.org/) [Jupyter Book](https://jupyterbook.org/) platform. All of the content for this tutorial material is publicly accessible, available, and version controlled in the GitHub repository (https://github.com/OpenSourceEcon/CompMethods) associated with this book. Some of the functionality of this tutorial site includes the following: +* **Navigate** through the chapters and sections of the tutorial materials using the chapter table of contents on the left side of the site, and navigate through subsections of each chapter using the subsection table of contents on the right side of each page. +* Click on the GitHub icon in the upper-right of each page to go to the **GitHub repository** or open and issue in the repository. +* **Download** each page as a markdown file `.md` or a PDF file `.pdf` by clicking on the download icon in the upper-right of each page. +* Toggle between a desktop window or **full-screen mode** by clicking on the full screen icon in the upper-right of each page. +* Change the **background** from light to dark to automatic using the background brightness icon in the upper-right of each page. +* **Search** for terms in the training materials using by clicking on the search icon in the upper-fight of each page and entering your search terms. + + +## Associated repository components +Put here a description of the code and tests available in the repository. + + +## Citing this book +Please use the following citation form for this book. + +General citation to the book: +* Evans, Richard W., *Computational Methods for Economists using Python*, Open access Jupyter Book, v#.#.#, 2023, [url to book]. + +Citation to a chapter in the book: +* Evans, Richard W., "[insert chapter name]", in *Computational Methods for Economists using Python*, Open access Jupyter Book, v#.#.#, 2023, [url to chapter]. diff --git a/docs/book/python/DocStrings.md b/docs/book/python/DocStrings.md new file mode 100644 index 0000000..1b58db5 --- /dev/null +++ b/docs/book/python/DocStrings.md @@ -0,0 +1,20 @@ +(Chap_DocStrings)= + + +# Docstrings and Documentation + +Quote about yourself 6 months from now trying to climb back into code... + +Good documentation is critical to the ability to disseminate your work and allow others to reproduce it - and that includes yourself several months from now when you may have forgotten why you did something a certain way. Python scripts allow for two types of comments: inline comments (which are usually a line or two at a time) and docstrings, which are longer blocks set aside to document the source code. + +Here we show the uses of each of these. More... + +Docstrings also have the power to help with automatric documentation of your codes API. Talk about sphinx and docstring styles (e.g., google and Numpy)... + + +## Exercises + +1. Inline comment excercise +2. Use Google docstring style to format a function that is the FOC_savings function (worked with in SciPy exercises) +3. Create auto documentation of (2) with Sphinx? +4. Other?? diff --git a/docs/book/python/Matplotlib.md b/docs/book/python/Matplotlib.md new file mode 100644 index 0000000..3f4de0e --- /dev/null +++ b/docs/book/python/Matplotlib.md @@ -0,0 +1,17 @@ +(Chap_Matplotlib)= + + +# Matplotlib + +Many plotting packages for Python. Some of the most popular are [Matplotlib](https://matplotlib.org/), [Plotly](https://plotly.com/), [Bokeh](http://bokeh.org/), and [Seaborn](https://seaborn.pydata.org/). Of these, Matplotlib is the most general for static images and is what is used on `OG-Core`. Once you have a general idea of how to create plots in Python, that knowlege will generalize (to varying degrees) to the other plotting packages. + +ACME materials link... + + +# Exercises + +1. Take UN pop data, create line plot +2. Format it - title, font, legened, etc +3. Collapse data and create bar plot +4. Plot mulitple series +5. Grouped bar plot \ No newline at end of file diff --git a/docs/book/python/NumPy.md b/docs/book/python/NumPy.md new file mode 100644 index 0000000..77ece84 --- /dev/null +++ b/docs/book/python/NumPy.md @@ -0,0 +1,25 @@ +(Chap_Numpy)= + + +# NumPy + +ACME materials link... + + +# Exercises + +TODO: update excerises to be more relevant to OG-Core. e.g., matrix represents savings. Then we do some array operations to multiple savings by the "population distribution" matrix omega. Then sum to get total savings, accounting for population weights. + +1. Create a Numpy array `b` (defined this as the savings of 2 types of agents over 5 periods): + $$ \[ +M= + \begin{bmatrix} + 1 & 2 & 3 & 4 & 5 \\ + 3 & 4 & 5 & 6 & 7 + \end{bmatrix} +\]. Use the `shape` method of Numpy arrays to print the shape of this matrix. Use array slicing to print the first row of `A`. Use array slicing to print the second column of `A`. Use array slicing to print the first two rows and the last three columns of `A`. +2. Reshape the matrix `A` unto a 5x2 matrix. Assign this new matrix to name `B`. Use matrix multiplication to find `C`, which is the dot product of `A` and `B`. +3. Multiply the matrix `A` by itself element-wise (Hadamard product). +4. In one line, create a matrix of zeros that is the same size as `A`. +5. Something with `np.where`. +6. Something with appending/stacking. \ No newline at end of file diff --git a/docs/book/python/OOP.md b/docs/book/python/OOP.md new file mode 100644 index 0000000..bc7718a --- /dev/null +++ b/docs/book/python/OOP.md @@ -0,0 +1,15 @@ +(Chap_OOP)= + + +# Object Oriented Programming + +ACME materials link... + + +# Exercises + +1. Define a class called `Specifications` with an attribute that is the rate of time preference, $\beta$. Create instances of this class called `p` for $\beta=0.96$ and $\beta=0.99$. +2. Update the `Specifications` class so that allows one to specify the value of $\beta$ upon initialization of the class and checks that $\beta$ is between 0 and 1. +3. Modify the `Specifications` class so that it has a method that prints the value of $\beta$. +4. Change the input of $\beta$ to the class so that it is input at an annual rate. Allow another attribute of the class called `S` that is the number of periods in an economic agent's life. Include a method in the `Specifications` class that adjusts the value the value of $\beta$ to represent the discount rate applied per model period, which will be equivalent to `S/80` years. +5. Add a method to the `Specifications` class that allows one to update the values of the class attributes `S` and `beta_annual` by providing a dictionary of the form `{"S": 40, "beta_annual": 0.8}`. Ensure that when the instance is updated, the new `beta` attribute is consistent with the new `S` and `beta_annual`. \ No newline at end of file diff --git a/docs/book/python/Pandas.md b/docs/book/python/Pandas.md new file mode 100644 index 0000000..02326d7 --- /dev/null +++ b/docs/book/python/Pandas.md @@ -0,0 +1,21 @@ +(Chap_Pandas)= + + +# Pandas + +ACME materials link... + + +# Exercises + +1. Creating a DataFrame from a dictionary. Simple example with GDP and inflation for a small set of countries over a few years. +2. Inspecting a DataFrame with `head` and `tail` and `describe` and `keys` +3. Something to illustrate indexing. Can turn dataframe into a panel with multindex. +4. Using `groupby` to aggregate data. +5. Printing a DataFrame as a table (e.g. to tex or json or md) +6. Read in a csv file as a DataFrame. Use UN population data as an example. Saving a DataFrame to a CSV file. +7. Creating a new variable in a DataFrame. +8. Selecting a subset of a DataFrame. Using `.loc` and subsetting columns etc +9. Using `merge` to join two DataFrames. Read other UN data (e.g., fertility) and merge with data from (4) +10. Using the `plot` method +11. Replacing values, dropping, renaming columns \ No newline at end of file diff --git a/docs/book/python/SciPy.md b/docs/book/python/SciPy.md new file mode 100644 index 0000000..e2b99e0 --- /dev/null +++ b/docs/book/python/SciPy.md @@ -0,0 +1,15 @@ +(Chap_Scipy)= + + +# SciPy + +ACME materials link... + + +# Exercises + +1. Define household FOC for savings and use `scipy.optimize.root` to solve for the optimal savings rate for a household with CRRA utility +2. Define the household FOC for labor supply and use `scipy.optimize.root` to solve for the optimal labor supply for a household with ellipitcal utility +3. Use `scipy.optimize.minimize` to minimize the function $f(x) = x^2 + 2x + 1$ (or some other function). +4. Use `scipy.optimize.minimize` to minimize the function $f(x) = x^2 + 2x + 1$ (or some other function) subject to the constraint that $x \geq 2$. +5. Use `scipy.interpolate`... \ No newline at end of file diff --git a/docs/book/python/StandardLibrary.md b/docs/book/python/StandardLibrary.md new file mode 100644 index 0000000..37b8623 --- /dev/null +++ b/docs/book/python/StandardLibrary.md @@ -0,0 +1,15 @@ +(Chap_StdLib)= + + +# Python Standard Library + +ACME materials link... + + +# Exercises + +1. Determining which of Python's build in objects (string, dict, list, tuple, set, int) are mutable and which are immutable. +2. Create a python module and run it from the command line +3. Create a python notebook and run it from VS Code +4. Write a function in the notebook and run it +5. Use the `sys` module to create a relative path from a Python module, print that path \ No newline at end of file diff --git a/docs/book/python/UnitTesting.md b/docs/book/python/UnitTesting.md new file mode 100644 index 0000000..549c104 --- /dev/null +++ b/docs/book/python/UnitTesting.md @@ -0,0 +1,14 @@ +(Chap_UnitTesting)= + + +# Unit Testing + +Testing of your source code is important to ensure that the results of your code are accurate and to cut down on debugging time. Fortunately, `Python` has a nice suite of tools for unit testing. In this section, we will introduce the `pytest` package and show how to use it to test your code. + +# Exercises + +1. Take simple function to minimize from SciPy and write a unit test for it (know analytic solutions so can test that SciPy is working correctly) +2. Another single test where assert that object a certain type +3. Use the `@pytest.mark.parametrize` decorator to test a function for multiple inputs +4. Use pytest markers to skip a test +5. ??? \ No newline at end of file diff --git a/docs/book/python/intro.md b/docs/book/python/intro.md new file mode 100644 index 0000000..b138cb8 --- /dev/null +++ b/docs/book/python/intro.md @@ -0,0 +1,88 @@ +(Chap_PythonIntro)= +# Introduction to Python + +The `OG-Core` model, as well as the country-specific calibration packages, are written in the Python programming language. These training materials will provide you with sufficient background with Python and some of its most-used packages for data science that you will be able to understand and contribute to the source code underlying `OG-Core` and the calibration packages. We assume some basic background with mathematics, economics, and programming, but we do not assume any prior knowledge of Python. + +As we walk you through the basics of Python, we will leverage some excellent open source materials put together by [QuantEcon](https://quantecon.org/) and the [Applied and Computational Mathematics Emphasis at BYU (BYU ACME)](https://acme.byu.edu/). And while we will point you to their tutorials, we have customized all our excercises to be relevant to the `OG-Core` model and the calibration packages. + + +(SecPythonIntroOverview)= +## Overview of Python +The Python.org site has documentation essays, one of which is entitled "[What is Python? Executive Summary](https://www.python.org/doc/essays/blurb/)". The first paragraph contains the following description. + +> Python is an interpreted, object-oriented, high-level programming language with dynamic semantics. Its high-level built in data structures, combined with dynamic typing and dynamic binding, make it very attractive for Rapid Application Development, as well as for use as a scripting or glue language to connect existing components together. Python's simple, easy to learn syntax emphasizes readability and therefore reduces the cost of program maintenance. Python supports modules and packages, which encourages program modularity and code reuse. The Python interpreter and the extensive standard library are available in source or binary form without charge for all major platforms, and can be freely distributed. + +In addition to the description above, Python is an open source programming language that is freely available and customizable (see https://www.python.org/downloads/source/). + +Python has some built in functionality with the standard library, but most of the functionality comes from packages that are developed by the open source community. The most important packages for data science are: NumPy, SciPy, Pandas, and Matplotlib. We will introduce each of these packages as we go through the training materials as they are used heavily in `OG-Core` and the corresponding country calibration packages. + + +(SecPythonIntroInstall)= +## Installing Python +We recommend that you download the Anaconda distribution of Python provided by [Anaconda](https://www.anaconda.com/download). We also recommend the most recent stable version of Python, which is currently Python 3.11. This can be done from the [Anaconda download page](https://www.anaconda.com/download) for Windows, Mac OSX, and Linux machines. The code we will be writing uses common Python libraries such as `NumPy`, `SciPy`, `pickle`, `os`, `matplotlib`, and `time`, which are all included in the Anaconda distribution. If you are using a different distribution of Python, you may need to install these packages separately. + + +(SecPythonIntroWorkingWith)= +## Working with Python + +There are several ways to interact with Python: +1. [Jupyter Notebook](https://jupyter.org/) +2. iPython session +3. Running a Python script from the command line +4. Running a Python script from an IDE such as [Spyder](https://www.spyder-ide.org/). + +In our recommended Python development workflow, you will write Python scripts and modules (`*.py` files) in a text editor. Then you will run those scripts from your terminal. You will want a capable text editor for developing your code. Many capable text editors exist, but we recommend [Visual Studio Code](https://code.visualstudio.com) (VS Code). As you learn Python and complete the exercises in this training program, you will also use Python interactively in a Jupyter Notebook or iPython session. VS Code will be helpful here as well as it will allow you open Jupyter Notebooks and run Python interactively through the text editor. + +VS Code is free and will be included with your installation of Anaconda. This is a very capable text editor and will include syntax highlighting for Python and and built in Git controls. In addition to the basics, you may want to use a more advanced linter for Python. This will help you correct syntax errors on the fly and provide helpful information as you declare objects and call functions. [This link](https://code.visualstudio.com/docs/python/linting) provides step-by-step instructions on using more advanced linting in VS Code. + +Some extensions that we recommend installing into your VS Code: +* cornflakes-linter +* Git Extension Pack +* GitLens +* Jupyter +* Markdown All in One +* Pylance + +In addition, [GitHub Copilot](https://github.com/features/copilot) is an amazing resource and can be added as an extension to VS Code. However, this service is not free of charge and does require an internet connection to work. + +```{exercise-start} +:label: ExerPythonIntro +``` +Read the BYU ACME "[Introduction to Python](https://acme.byu.edu/00000181-448a-d778-a18f-dfcae22f0001/intro-to-python)" lab and complete Problems 1 through 8 in the lab. {cite}`BYUACME_PythonIntro` +```{exercise-end} +``` + +[Put a review of Python data types here: string, byte, float, list, set, dict. Discuss mutability versus immutability as well as iterability. Also introduce NumPy arrays and Pandas DataFrames.] + + +(SecPythonIntroPackages)= +## Python Packages + +When using `OG-Core` there are a handful of Python packages that will be useful and that these training materials will cover: + +1. The Standard Library +2. NumPy for numerical computing (e.g., arrays, linear algebra, etc.) +3. Pandas for data analysis +4. Matplotlib for plotting +5. SciPy for scientific computing (e.g., optimization, interpolation, etc.) + +All of these will be included as part of your installation of Anaconda. Anaconda also includes a package manager called `conda` that will allow you to install additional packages and well help keep versions of packages consistent with each other. We will not cover this in these training materials, but you can find more information about `conda` [here](https://docs.conda.io/en/latest/) and you'll find references to `conda` as we install the `OG-Core` package in the latter part of these training materials. + + +(SecPythonIntroTopics)= +## Python Training Topics + +1. [Python Standard Library](StandardLibrary.md) +2. [Object Oriented Programming](OOP.md) +3. [NumPy](NumPy.md) +4. [Pandas](Pandas.md) +5. [Matplotlib](Matplotlib.md) +6. [SciPy](SciPy.md) +7. [Doc strings and comments](DocStrings.md) +8. [Unit testing in Python](UnitTesting.md) + + + + + diff --git a/docs/book/struct_est/GMM.md b/docs/book/struct_est/GMM.md new file mode 100644 index 0000000..dbe6271 --- /dev/null +++ b/docs/book/struct_est/GMM.md @@ -0,0 +1,10 @@ +(Chap_GMM)= +# Generalized Method of Moments + +Put GMM chapter here. + + +(SecGMMFootnotes)= +## Footnotes + + diff --git a/docs/book/struct_est/SMM.md b/docs/book/struct_est/SMM.md new file mode 100644 index 0000000..99a61d8 --- /dev/null +++ b/docs/book/struct_est/SMM.md @@ -0,0 +1,10 @@ +(Chap_SMM)= +# Simulated Method of Moments + +Put SMM chapter here. + + +(SecSMMFootnotes)= +## Footnotes + + diff --git a/docs/book/struct_est/intro.md b/docs/book/struct_est/intro.md new file mode 100644 index 0000000..8ed59a8 --- /dev/null +++ b/docs/book/struct_est/intro.md @@ -0,0 +1,10 @@ +(Chap_StructEstIntro)= +# Structural Estimation + +Put structural estimation intro here. + + +(SecStructEstIntroFootnotes)= +## Footnotes + + diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 0000000..38918e8 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..01acdd3 --- /dev/null +++ b/environment.yml @@ -0,0 +1,27 @@ +name: compmethods-dev +channels: +- conda-forge +dependencies: +- python>=3.10 +- numpy +- scipy +- pandas +- ipython +- matplotlib +- bokeh +- sphinx +- sphinx-argparse +- sphinxcontrib-bibtex>=2.0.0 +- sphinx-math-dollar +- pydata-sphinx-theme +- jupyter-book>=0.11.3 +- jupyter +- black +- setuptools +- pytest +- coverage +- pip +- pip: + - linecheck + - yaml-changelog + - sphinx-exercise diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..903252e --- /dev/null +++ b/setup.py @@ -0,0 +1,55 @@ +"""This file contains the fiscalsim-us package's metadata and dependencies.""" + +from setuptools import find_packages, setup + +with open("README.md", "r") as readme_file: + readme = readme_file.read() + +setup( + name="UN-OG-Training", + version="0.0.0", + author="Jason DeBacker and Richard W. Evans", + author_email="rickecon@gmail.com", + long_description=readme, + long_description_content_type="text/markdown", + classifiers=[ + "Development Status :: 5 - Production/Stable", + "License :: OSI Approved :: GNU Affero General Public License v3", + "Operating System :: POSIX", + "Programming Language :: Python", + "Programming Language :: Python :: 3.9", + "Topic :: Scientific/Engineering :: Information Analysis", + ], + description="UN open source OG-Core overlapping generations macroeconomic model training", + keywords="tax benefit macroeconomic dynamic general equilibrium fiscal", + license="http://www.fsf.org/licensing/licenses/agpl-3.0.html", + url="https://github.com/OpenRG/UN-OG-Training", + include_package_data=True, # Will read MANIFEST.in + install_requires=[ + "numpy", + "scipy", + "pandas", + "ipython", + "matplotlib", + "bokeh", + "sphinx", + "sphinx-argparse", + "sphinx-exercise", + "sphinxcontrib-bibtex>=2.0.0", + "sphinx-math-dollar", + "pydata-sphinx-theme", + "jupyter-book>=0.11.3", + "jupyter", + "black", + "setuptools", + "pytest", + "coverage", + "ogcore", + "linecheck", + "yaml-changelog", + ], + # Windows CI requires Python 3.9. + python_requires=">=3.10", + tests_require=["pytest"], + packages=find_packages(), +) diff --git a/tests/test_add_junk.py b/tests/test_add_junk.py new file mode 100644 index 0000000..0010392 --- /dev/null +++ b/tests/test_add_junk.py @@ -0,0 +1,36 @@ +# import sys + +# sys.path.append("/Users/richardevans/Docs/Economics/OSE/CompMethods/code/") + +import pytest + +# from junk_funcs import junk_func_add + + +def junk_func_add(arg1, arg2): + """ + This is just a junk function that duplicates the `junk_funcs.py` module in + the `/code/` directory. We can delete this as soon as we have some real + functions. + """ + junk_sum = arg1 + arg2 + + return junk_sum + + +@pytest.mark.parametrize( + "arg1, arg2, expected", + [(2, 3, 5), (10, 17, 27)], + ids=[ + "2 plus 3 equals 5", + "10 plus 17 equals 27", + ], +) +def test_junk_func_add(arg1, arg2, expected): + """ + This is just a fake test of code in the `/code/` directory. We can delete + this as soon as we have some real tests. + """ + junk_sum = junk_func_add(arg1, arg2) + + assert junk_sum == expected