Merge pull request #745 from rickecon/docs

Update OG-Core documentation
PSLmodels · Aug 30, 2021 · 2772942 · 2772942
2 parents 1abf952 + e1db774
commit 2772942
Show file tree

Hide file tree

Showing 32 changed files with 223 additions and 100 deletions.
diff --git a/.github/workflows/deploy_docs.yml b/.github/workflows/deploy_docs.yml
@@ -1,7 +1,7 @@
 name: Build and Deploy Jupyter Book documentation
 on:
   push:
-    branches:    
+    branches:
       - master
 jobs:
   build-and-deploy:
@@ -35,4 +35,4 @@ jobs:
         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.
+          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
@@ -9,7 +9,7 @@ jobs:
         uses: actions/checkout@v2 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly.
         with:
           persist-credentials: false
-  
+
       - name: Setup Miniconda
         uses: conda-incubator/setup-miniconda@v2
         with:

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 # OG-Core
 
-OG-Core is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy.  OG-Core provides a general framework and is a dependency of several country-specific OG models, such as [OG-USA](https://github.com/PSLmodels/OG-USA) and [OG-UK](https://github.com/PSLmodels/OG-UK).  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 [here](https://pslmodels.github.io/OG-Core).
+OG-Core is an overlapping-generations (OG) model core theory, logic, and solution method algorithms that allow for dynamic general equilibrium analysis of fiscal policy. OG-Core provides a general framework and is a dependency of several country-specific OG models, such as [OG-USA](https://github.com/PSLmodels/OG-USA) and [OG-UK](https://github.com/PSLmodels/OG-UK). 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 [here](https://pslmodels.github.io/OG-Core).
 
 
 ## Disclaimer
@@ -45,6 +45,14 @@ If you run into errors running the example script, please open a new issue in th
 The CSV output file `./run_examples/ogcore_example_output.csv` can be compared to the `./run_examples/expected_ogcore_example_output.csv` file that is checked into the repository to confirm that you are generating the expected output. The easiest way to do this is to use the `sh example-diffs` command (or `example-diffs` on Windows) from the `run_examples` directory. If you run into errors running the example script, please open a new issue in the OG-Core repo with a description of the issue and any relevant tracebacks you receive.
 
 
+## 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-Core
 
 OG-Core (Version 0.0.0)[Source code], https://github.com/PSLmodels/OG-Core
diff --git a/docs/book/_config.yml b/docs/book/_config.yml
@@ -58,5 +58,5 @@ latex:
   latex_documents:
     targetname           : book.tex
 bibtex_bibfiles:
-   - OGUSA_references.bib
-   - ../../citations.bib
+   - OGCore_references.bib
+   - citations.bib
diff --git a/docs/book/_toc.yml b/docs/book/_toc.yml
@@ -7,28 +7,10 @@ parts:
 - caption: OG-Core API
   chapters:
   - file: content/api/public_api
-    sections:
-    - file: content/api/aggregates
-    - file: content/api/demographics
-    - file: content/api/elliptical_u_est
-    - file: content/api/execute
-    - file: content/api/firm
-    - file: content/api/fiscal
-    - file: content/api/get_micro_data
-    - file: content/api/household
-    - file: content/api/income
-    - file: content/api/output_plots
-    - file: content/api/output_tables
-    - file: content/api/parameter_plots
-    - file: content/api/parameter_tables
-    - file: content/api/parameters
-    - file: content/api/tax
-    - file: content/api/txfunc
-    - file: content/api/utils
-    - file: content/api/wealth
 - caption: OG-Core Theory
   chapters:
   - file: content/theory/intro
+  - file: content/theory/demographics
   - file: content/theory/households
   - file: content/theory/firms
   - file: content/theory/government
@@ -41,7 +23,7 @@ parts:
   - file: content/theory/derivations
 - caption: References
   chapters:
-  - file: content/theory/references
+  - file: content/OGCore_references
 - caption: Citations of OG-Core
   chapters:
   - file: content/citations
diff --git a/citations.bib → docs/book/citations.bib b/citations.bib → docs/book/citations.bib
diff --git a/docs/book/content/OGCore_references.md b/docs/book/content/OGCore_references.md
@@ -0,0 +1,5 @@
+# References
+
+```{bibliography} ../OGCore_references.bib
+:style: alpha
+```
diff --git a/docs/book/content/api/aggregates.rst b/docs/book/content/api/aggregates.rst
@@ -3,13 +3,11 @@
 Aggregates Equations
 =====================
 
-**Aggregates**
+**aggregates.py modules**
 
 ogcore.aggregates
 ------------------------------------------
 
-.. currentmodule:: ogcore.aggregates
-
 .. automodule:: ogcore.aggregates
   :members: get_L, get_I, get_B, get_BQ, get_C, revenue, get_r_hh,
     resource_constraint, get_K_splits
diff --git a/docs/book/content/api/elliptical_u_est.rst b/docs/book/content/api/elliptical_u_est.rst
@@ -1,15 +1,13 @@
 .. _elliptical_u_est:
 
-Elliptical Utility Function Estimation Functions
+Elliptical Utility Function Estimation
 =================================================
 
-**Elliptical Utility Estimation**
+**elliptical_u_est.py modules**
 
 ogcore.elliptical_u_est
 ------------------------------------------
 
-.. currentmodule:: ogcore.elliptical_u_est
-
 .. automodule:: ogcore.elliptical_u_est
   :members: CFE_u, CFE_mu, elliptical_u, elliptical_mu, sumsq, sumsq_MU,
     estimation
diff --git a/docs/book/content/api/execute.rst b/docs/book/content/api/execute.rst
@@ -3,12 +3,10 @@
 Model Execution Functions
 =================================================
 
-**Model Execution**
+**execute.py modules**
 
 ogcore.execute
 ------------------------------------------
 
-.. currentmodule:: ogcore.execute
-
 .. automodule:: ogcore.execute
   :members: runner
diff --git a/docs/book/content/api/firm.rst b/docs/book/content/api/firm.rst
@@ -1,15 +1,13 @@
 .. _firm:
 
-Firm Equations
+Firm Functions
 ===============
 
-**Firm**
+**firm.py modules**
 
 ogcore.firm
 ------------------------------------------
 
-.. currentmodule:: ogcore.firm
-
 .. automodule:: ogcore.firm
   :members: get_Y, get_r, get_w, get_KLratio_from_r, get_w_from_r, get_K,
     get_K_from_Y
diff --git a/docs/book/content/api/fiscal.rst b/docs/book/content/api/fiscal.rst
@@ -3,12 +3,10 @@
 Fiscal Functions
 =================================================
 
-**Government Budget Functions**
+**fiscal.py modules**
 
 ogcore.fiscal
 ------------------------------------------
 
-.. currentmodule:: ogcore.fiscal
-
 .. automodule:: ogcore.fiscal
   :members: D_G_path, get_D_ss, get_G_ss, get_debt_service_f, get_TR, get_r_gov
diff --git a/docs/book/content/api/household.rst b/docs/book/content/api/household.rst
@@ -3,13 +3,11 @@
 Household Functions
 =================================================
 
-**Household Functions**
+**household.py modules**
 
 ogcore.household
 ------------------------------------------
 
-.. currentmodule:: ogcore.household
-
 .. automodule:: ogcore.household
   :members: marg_ut_cons, marg_ut_labor, get_bq, get_tr, get_cons, FOC_savings,
     FOC_labor, get_y, constraint_checker_SS, constraint_checker_TPI
diff --git a/docs/book/content/api/output_plots.rst b/docs/book/content/api/output_plots.rst
@@ -1,15 +1,13 @@
 .. _output_plots:
 
-OG-Core Output Plotting Functions
+Output Plotting Functions
 =================================================
 
-**OG-Core Output Plotting Functions**
+**output_plots.py modules**
 
 ogcore.output_plots
 ------------------------------------------
 
-.. currentmodule:: ogcore.output_plots
-
 .. automodule:: ogcore.output_plots
   :members: plot_aggregates, plot_gdp_ratio, ability_bar, ability_bar_ss,
     ss_profiles, tpi_profiles, plot_all
diff --git a/docs/book/content/api/output_tables.rst b/docs/book/content/api/output_tables.rst
@@ -1,15 +1,13 @@
 .. _output_tables:
 
-OG-Core Output Table Building Functions
+Output Table Functions
 =================================================
 
-**OG-Core Output Table Building Functions**
+**output_tabls.py modules*
 
 ogcore.output_tables
 ------------------------------------------
 
-.. currentmodule:: ogcore.output_tables
-
 .. automodule:: ogcore.output_tables
   :members: macro_table, macro_table_SS, ineq_table, gini_table,
     wealth_moments_table, tp_output_dump_table, dynamic_revenue_decomposition
diff --git a/docs/book/content/api/parameter_plots.rst b/docs/book/content/api/parameter_plots.rst
@@ -1,15 +1,13 @@
 .. _parameter_plots:
 
-OG-Core Parameter Plotting Functions
+Parameter Plotting Functions
 =================================================
 
-**OG-Core Parameter Plotting Functions**
+**parameter_plots.py modules**
 
 ogcore.parameter_plots
 ------------------------------------------
 
-.. currentmodule:: ogcore.parameter_plots
-
 .. automodule:: ogcore.parameter_plots
   :members: plot_imm_rates, plot_mort_rates, plot_pop_growth,
     plot_ability_profiles, plot_elliptical_u, plot_chi_n,

diff --git a/docs/book/content/api/parameter_tables.rst b/docs/book/content/api/parameter_tables.rst
@@ -1,14 +1,12 @@
 .. _parameter_tables:
 
-OG-Core Parameter Table Building Functions
+Parameter Table Functions
 =================================================
 
-**OG-Core Parameter Table Building Functions**
+**parameter_tables.py modules**
 
 ogcore.parameter_tables
 ------------------------------------------
 
-.. currentmodule:: ogcore.parameter_tables
-
 .. automodule:: ogcore.parameter_tables
   :members: tax_rate_table, param_table
diff --git a/docs/book/content/api/parameters.rst b/docs/book/content/api/parameters.rst
@@ -1,18 +1,17 @@
 .. _parameters:
 
-OG-Core Parameters
+Parameters Functions
 =================================================
 
-**OG-Core Parameters**
+**parameters.py classes, methods, and functions**
 
 ogcore.parameters
 ------------------------------------------
 
 .. currentmodule:: ogcore.parameters
 
-.. automodule:: ogcore.parameters
-  :members: reform_warnings_errors
-
 .. autoclass:: Specifications
-  :members: initialize, compute_default_params, get_tax_function_parameters,
-    read_tax_func_estimate, get_ubi_nom_objs, default_parameters, update_specifications
+  :members: initialize, compute_default_params, get_ubi_nom_objs, update_specifications
+
+.. automodule:: ogcore.parameters
+  :members: revision_warnings_errors
diff --git a/docs/book/content/api/tax.rst b/docs/book/content/api/tax.rst
@@ -3,13 +3,11 @@
 Tax Functions
 =================================================
 
-**Tax Functions**
+**tax.py modules**
 
 ogcore.tax
 ------------------------------------------
 
-.. currentmodule:: ogcore.tax
-
 .. automodule:: ogcore.tax
   :members: replacement_rate_vals, ETR_wealth, MTR_wealth, ETR_income,
     MTR_income, get_biz_tax, net_taxes, income_tax_liab, pension_amount,

diff --git a/docs/book/content/api/txfunc.rst b/docs/book/content/api/txfunc.rst
@@ -3,13 +3,11 @@
 Tax Function Estimation Functions
 =================================================
 
-**Tax Function Estimation Functions**
+**txfunc.py modules**
 
 ogcore.txfunc
 ------------------------------------------
 
-.. currentmodule:: ogcore.txfunc
-
 .. automodule:: ogcore.txfunc
   :members: gen_3Dscatters_hist, plot_txfunc_v_data, get_tax_rates, wsumsq,
     find_outliers, replace_outliers, txfunc_est, tax_func_loop,

diff --git a/docs/book/content/api/utils.rst b/docs/book/content/api/utils.rst
@@ -3,18 +3,18 @@
 Utilities Functions
 =================================================
 
-**Utilities Functions**
+**utils.py classes, methods, and modules**
 
 ogcore.utils
 ------------------------------------------
 
 .. currentmodule:: ogcore.utils
 
 .. autoclass:: Inequality
-  :members: gini, var_of_logs, ratio_pct1_pct2, topshare
+  :members: gini, var_of_logs, ratio_pct1_pct2, pct, topshare
 
 .. automodule:: ogcore.utils
   :members: mkdirs, pct_diff_func, convex_combo, read_file, pickle_file_compare,
     comp_array, comp_scalar, dict_compare, to_timepath_shape, get_initial_path,
-    safe_read_pickle, rate_conversion, save_return_table, Inequality,
+    safe_read_pickle, rate_conversion, save_return_table,
     read_cbo_forecast, print_progress, fetch_files_from_web, not_connected
diff --git a/docs/book/content/api/wealth.rst b/docs/book/content/api/wealth.rst
@@ -3,12 +3,10 @@
 Wealth Functions
 =================
 
-**Wealth**
+**wealth.py modules**
 
 ogcore.wealth
 ------------------------------------------
 
-.. currentmodule:: ogcore.wealth
-
 .. automodule:: ogcore.wealth
   :members: get_wealth_data, compute_wealth_moments
diff --git a/docs/book/content/citations.md b/docs/book/content/citations.md
@@ -1,5 +1,5 @@
 # Citations and use cases of OG-Core
 
-```{bibliography} ../../../citations.bib
+```{bibliography} ../citations.bib
 :all :
 ```
diff --git a/docs/book/content/intro/intro.md b/docs/book/content/intro/intro.md
@@ -27,4 +27,4 @@ The model is continuously under development. Users will be notified through [clo
 (Sec_CitingOGUSA)=
 ## Citing OG-Core
 
-`OG-Core` (Version 0.6.3)[Source code], https://github.com/PSLmodels/OG-Core
+`OG-Core` (Version 0.6.4)[Source code], https://github.com/PSLmodels/OG-Core