update docs to reduce jb warnings

jdebacker · jdebacker · commit 0cd89f6a3372 · 2024-06-15T21:36:49.000-04:00
diff --git a/docs/book/citations.bib b/docs/book/citations.bib
@@ -7,21 +7,6 @@ @TECHREPORT{DeBackerEtAl:2017b
   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 {J}oe {B}iden’s tax proposals, {O}ctober 2020 update},
diff --git a/docs/book/content/api/utils.rst b/docs/book/content/api/utils.rst
@@ -11,7 +11,7 @@ ogcore.utils
 .. currentmodule:: ogcore.utils
 
 .. autoclass:: Inequality
-  :members: gini, var_of_logs, ratio_pct1_pct2, pct, topshare
+  :members: gini, var_of_logs, ratio_pct1_pct2, pct, top_share
 
 .. autoclass:: CustomHttpAdapter
   :members: init_poolmanager
diff --git a/docs/book/content/contributing/contributor_guide.md b/docs/book/content/contributing/contributor_guide.md
@@ -29,36 +29,36 @@ If you have already completed the {ref}`Sec_SetupPython` and {ref}`Sec_SetupGit`
 
 6. Create a local repo by entering at the command line the text after the $.[^commandline_note] This step creates a directory called `OG-Core` in the directory that you specified in the prior step:
 
-    ```
+    ```console
       git clone https://github.com/[github-username]/OG-Core.git
     ```
 
 7. From your command line or terminal, navigate to your local `OG-Core` directory.
 
 8. Make it easier to [push](https://help.github.com/articles/github-glossary/#pull) your local work to others and [pull](https://help.github.com/articles/github-glossary/#pull) others' work to your local machine by entering at the command line:
 
-    ```
+    ```console
       $ cd OG-Core
       OG-Core$ git remote add upstream https://github.com/PSLmodels/OG-Core.git
     ```
 
 9. Create a conda environment with all of the necessary packages to
    execute the source code:
 
-    ```
+    ```console
       OG-Core$ conda env create
     ```
 
 10. The prior command will create a conda environment called `ogcore-dev`.
     Activate this environment as follows:
 
-    ```
+    ```console
       OG-Core$ conda activate ogcore-dev
     ```
 
 11. To make sure that the `ogcore` Python package from the `OG-Core` repository is installed and operational in your `ogcore-dev` conda environment, type the following command at your command prompt.
 
-    ```
+    ```console
     OG-Core$ pip install -e .
     ```
 
@@ -75,7 +75,6 @@ Don't be alarmed if the above paragraph is confusing. The following
 section introduces some standard Git practices and guides you through
 the contribution process.
 
-
 (Sec_Workflow)=
 ## Workflow
 
@@ -84,7 +83,6 @@ the contribution process.
 
 GitHub "issues" are an excellent way to ask questions, include code examples, and tag specific GitHub users.
 
-
 (Sec_GitHubPR)=
 ### Submitting a GitHub Pull Request
 
@@ -100,60 +98,75 @@ situations, in which case other contributors are here to help.
       Navigate to your local `OG-Core` directory and enter the
       following text at the command line:
 
-    ```
+    ```console
         OG-Core$ git checkout master
     ```
 
    b. Download all of the content from the central `OG-Core` repo:
-    ```
+
+    ```console
         OG-Core$ git fetch upstream
     ```
+
    c. Update your local master branch to contain the latest content of
       the central master branch using [merge](https://help.github.com/articles/github-glossary/#merge). This step ensures that
       you are working with the latest version of `OG-Core`:
-    ```
+
+    ```console
         OG-Core$ git merge upstream/master
     ```
+
    d. Push the updated master branch in your local repo to your GitHub repo:
-    ```
+
+    ```console
         OG-Core$ git push origin master
     ```
+
 2. Create a new [branch](https://help.github.com/articles/github-glossary/#branch) on your local machine. Think of your
    branches as a way to organize your projects. If you want to work on
    this documentation, for example, create a separate branch for that
    work. If you want to change an element of the `OG-Core` model, create
    a different branch for that project:
-    ```
+
+    ```console
      OG-Core$ git checkout -b [new-branch-name]
     ```
+
 3. As you make changes, frequently check that your changes do not
    introduce bugs or degrade the accuracy of the `OG-Core`. To do
    this, run the following command from the command line from inside
    the `OG-Core/ogcore` directory:
-    ```
+
+    ```console
      OG-Core/ogcore$  pytest
     ```
+
    Note that running this full suite of tests may take more than 6 hours (depending on your hardware). To run the subset of tests that run on each pull request (and take about 40 minutes), use  `pytest -m "not local"`.  If the tests do not pass, try to fix the issue by using the information provided by the error message. If this isn't possible or doesn't work, the core maintainers are here to help via a [GitHub Issue](https://github.com/PSLmodels/OG-Core/issues).
 
 4. Now you're ready to [commit](https://help.github.com/articles/github-glossary/#commit) your changes to your local repo using the code below. The first line of code tells `Git` to track a file. Use the `git status` command to find all the files you have edited, and `git add` command to add each of the files that you would like `Git` to track. As a rule, do not add large files. If you'd like to add a file that is larger than 25 MB, please contact the other contributors and ask how to proceed. The second line of code commits your changes to your local repo and allows you to create a commit message. This should be a short description of your changes.
 
    *Tip*: Committing often is a good idea as `Git` keeps a record of your changes. This means that you can always revert to a previous version of your work if you need to. Do this to commit:
-    ```
+
+    ```console
      OG-Core$ git add [filename]
      OG-Core$ git commit -m "[description-of-your-commit]"
     ```
 
 5. Periodically, make sure that the branch you created in step 2 is in sync with the changes other contributors are making to the central master branch by fetching upstream and merging upstream/master into your branch:
-    ```
+
+    ```console
       OG-Core$ git fetch upstream
       OG-Core$ git merge upstream/master
     ```
+
    You may need to resolve conflicts that arise when another contributor changed the same section of code that you are changing. Feel free to ask other contributors for guidance if this happens to you. If you do need to fix a merge conflict, re-run the test suite afterwards (step 4.)
 
 6. When you are ready for other team members to review your code, make your final commit and push your local branch to your remote repo:
-    ```
+
+    ```console
      OG-Core$ git push origin [new-branch-name]
     ```
+
 7. From the GitHub.com user interface, [open a pull request](https://help.github.com/articles/creating-a-pull-request/#creating-the-pull-request).
 
 8. When you open a GitHub pull request, a code coverage report will be automatically generated. If your branch adds new code that is not tested, the code coverage percent will decline and the number of untested statements ("misses" in the report) will increase. If this happens, you need to add to your branch one or more tests of your newly added code. Add tests so that the number of untested statements is the same as it is on the master branch.
@@ -166,13 +179,13 @@ situations, in which case other contributors are here to help.
 
 1. Navigate to your local `OG-Core` repository in the terminal of your local machine and activate the `ogcore-dev` conda environment. If you have not created the `ogcore-dev` conda environment, follow steps 1-11 in Section {ref}`Sec_SetupGit` above.
 
-    ```
+    ```console
     OG-Core$ conda activate ogcore-dev
     ```
 
 2. Run the Python example script [`OG-Core/run_examples/run_ogcore_example.py`](https://github.com/PSLmodels/OG-Core/blob/master/run_examples/run_ogcore_example.py) by entering the following command in your terminal in your local machine `OG-Core` repository with the `ogcore-dev` conda environment activated.
 
-    ```
+    ```console
     (ogcore-dev) OG-Core$ python ./run_examples/run_ogcore_example.py
     ```
 
diff --git a/docs/book/content/theory/demographics.md b/docs/book/content/theory/demographics.md
@@ -11,7 +11,6 @@ kernelspec:
   name: ogcore-dev
 ---
 
-(glue)=
 
 (Chap_Demog)=
 # Demographics
diff --git a/docs/book/content/theory/equilibrium.md b/docs/book/content/theory/equilibrium.md
@@ -90,7 +90,7 @@ The computational algorithm for solving for the steady-state follows the steps b
         :label: EqSS_HHeul_bS
           (\bar{c}_{j,E+S})^{-\sigma} = e^{-\sigma g_y}\chi^b_j(\bar{b}_{j,E+S+1})^{-\sigma} \quad\forall j
         ```
-    6. Determine from the quantity of the composite consumption good consumed by each household, $\bar{c}_{j,s}$, use equation {eq}`EqHH_cmDem` to determine consumption of each output good, $\bar{c}_{m,j,s}$
+    6. Determine from the quantity of the composite consumption good consumed by each household, $\bar{c}_{j,s}$, use equation {eq}`EqStnrz_cmDem2` to determine consumption of each output good, $\bar{c}_{m,j,s}$
     7. Using $\bar{c}_{m,j,s}$ in {eq}`EqCmt`, solve for aggregate consumption of each output good, $\bar{C}_{m}$
     8. Given values for $\bar{n}_{j,s}$ and $\bar{b}_{j,s+1}$ for all $j$ and $s$, solve for steady-state labor supply, $\bar{L}$, savings, $\bar{B}$
         1. Use $\bar{n}_{j,s}$ and the steady-state version of the stationarized labor market clearing equation {eq}`EqStnrzMarkClrLab` to get a value for $\bar{L}^{i}$.
@@ -196,7 +196,7 @@ Under alternative model configurations, the solution algorithm changes slightly.
 (SecSSeqlbResults)=
 ### Steady-state results: default specification
 
-  [TODO: Update the results in this section.] In this section, we use the baseline calibration described in Chapter {ref}`Chap_Calibr`, which includes the baseline tax law from `Tax-Calculator`, to show some steady-state results from `OG-Core`. Figures {numref}`FigSSeqlbHHcons`, {numref}`FigSSeqlbHHlab`, and {numref}`FigSSeqlbHHsave` show the household steady-state variables by age $s$ and lifetime income group $j$.
+  [TODO: Update the results in this section.] In this section, we use the baseline calibration described in Chapter {ref}`Chap_Calib`, which includes the baseline tax law from `Tax-Calculator`, to show some steady-state results from `OG-Core`. Figures {numref}`FigSSeqlbHHcons`, {numref}`FigSSeqlbHHlab`, and {numref}`FigSSeqlbHHsave` show the household steady-state variables by age $s$ and lifetime income group $j$.
 
   ```{figure} ./images/HHcons_SS.png
   ---
@@ -328,7 +328,7 @@ The stationary non-steady state (transition path) solution algorithm has followi
    2. From price of consumption goods, determine the price of the composite consmpution good, $\bar{p}$ using equation {eq}`EqCompPnorm2`
    3. The household problem can be solved with a multivariate root finder solving the $2S$ equations and unknowns at once for each $j$ and $1\leq t\leq T+S-1$. The root finder uses $2S$ household Euler equations  {eq}`EqStnrz_eul_n`, {eq}`EqStnrz_eul_b`, and {eq}`EqStnrz_eul_bS` to solve for each household's $2S$ lifetime decisions. The household decision rules for each type and birth cohort are solved separately.
    4. After solving the first iteration of time path iteration, subsequent initial values for the $J$, $2S$ root finding problems are based on the solution in the prior iteration. This speeds up computation further and makes the initial guess for the highly nonlinear system of equations start closer to the solution value.
-7. Determine from the quantity of the composite consumption good consumed by each household, $\hat{c}_{j,s,t}$, use equation {eq}`EqHH_cmDem` to determine consumption of each output good, $\hat{c}_{m,j,s,t}$
+7. Determine from the quantity of the composite consumption good consumed by each household, $\hat{c}_{j,s,t}$, use equation {eq}`EqStnrz_cmDem2` to determine consumption of each output good, $\hat{c}_{m,j,s,t}$
 8. Using $\hat{c}_{m,j,s,t}$ in {eq}`EqCmt`, solve for aggregate consumption of each output good, $\hat{C}_{m,t}$
 9.  Given values for $n_{j,s,t}$ and $\hat{b}_{j,s+1,t+1}$ for all $j$, $s$, and $t$, solve for aggregate labor supply, $\hat{L}_t$, and savings, $B_t$ in each period
     1.  Use $n_{j,s,t}$ and the stationarized labor market clearing equation {eq}`EqStnrzMarkClrLab` to get a value for $\hat{L}_t^{i}$.
@@ -345,17 +345,20 @@ The stationary non-steady state (transition path) solution algorithm has followi
     2. The capital-output ratio can be determined from the FOC for the firms' choice of capital: $\frac{\hat{K}_{m,t}}{\hat{Y}_{m,t}} = \gamma_m\left[\frac{r_t + \delta_{M,t} - \tau^{corp}_{m,t}\delta^{\tau}_{m,t} - \tau^{inv}_{m,t}\delta_{M,t}}{(1-\tau^{corp}_{m,t})p_{m,t}({Z}_{m,t})^\frac{\varepsilon_m -1}{\varepsilon_m}}\right]^{-\varepsilon_m}$
     3. Capital demand can thus be found: $\hat{K}_{m,t} = \frac{\hat{K}_{m,t}}{\hat{Y}_{m,t}} * \hat{Y}_{m,t}$
     4. Labor demand can be found by inverting the production function:
+
       ```{math}
       :label: EqTPI_solveL
         \hat{L}_{m,t} = \left(\frac{\left(\frac{\hat{Y}_{m,t}}{Z_{m,t}}\right)^{\frac{\varepsilon_m-1}{\varepsilon_m}} - \gamma_{m}^{\frac{1}{\varepsilon_m}}\hat{K}_{m,t}^{\frac{\varepsilon_m-1}{\varepsilon_m}} - \gamma_{g,m}^{\frac{1}{\varepsilon_m}}\hat{K}_{g,m,t}^{\frac{\varepsilon_m-1}{\varepsilon_m}}}{(1-\gamma_m-\gamma_{g,m})^{\frac{1}{\varepsilon_m}}}\right)^{\frac{\varepsilon_m}{\varepsilon_m-1}}
       ```
+
     5. Use the interest rate $r_t^*$ and labor demand $\hat{L}_{m,t}$ to solve for private capital demand at the world interest rate $\hat{K}_{m,t}^{r^*}$ using {eq}`EqFirmsMPKg_opt`
+
       ```{math}
       :label: EqTP_MPKg
         \hat{K}_{m,t}^{r^*} = \hat{L}_{m,t}\left(\frac{\hat{w}_t}{\frac{r_t + \delta_{M,t} - \tau^{corp}_{m,t}\delta^{\tau}_{m,t} - \tau^{inv}_{m,t}\delta_{M,t}}{1 - \bar{\tau}_{m,t}^b}}\right)^{\varepsilon_m} \frac{\gamma_m}{(1 - \gamma_m - \gamma_{g,m})}
       ```
 
-18.  Determine factor demands and output for industry $M$:
+18. Determine factor demands and output for industry $M$:
      1. $\hat{L}_{M,t} = \hat{L}_t - \sum_{m=1}^{M-1}\hat{L}_{m,t}$
      2. Find $\hat{K}_{m,t}^{r^*}$ using {eq}`EqFirmsMPKg_opt`
      3. Find total capital supply, and the split between that from domestic and foreign households: $\hat{K}_t^{i'}$, $\hat{K}_t^d$, $\hat{K}_t^f$:
@@ -385,7 +388,7 @@ The stationary non-steady state (transition path) solution algorithm has followi
      5. $error_{bq} =  max\left\{\frac{\hat{BQ}_{t}^{\,i'} - \hat{BQ}_{t}^{\,i}}{\hat{BQ}_{t}^{\,i}}\right\}_{t=0}^{T}$
      6. $error_{tr} = \left\{\frac{\hat{TR}_{t}^{\,i'} - \hat{TR}_{t}^{\,i}}{\hat{TR}_{t}^{\,i}}\right\}_{t=0}^{T}$
 
-23.  If the maximum absolute error among the four outer loop error terms is greater than some small positive tolerance $toler_{tpi,out}$, $\max\big|\left(error_{r_p}, error_r, error_w, error_p, error_{bq},error_{tr}\right)\bigr| > toler_{tpi,out}$, then update the guesses for the outer loop variables as a convex combination governed by $\xi_{tpi}\in(0,1]$ of the respective initial guesses and the new implied values and repeat steps (3) through (5).
+23. If the maximum absolute error among the four outer loop error terms is greater than some small positive tolerance $toler_{tpi,out}$, $\max\big|\left(error_{r_p}, error_r, error_w, error_p, error_{bq},error_{tr}\right)\bigr| > toler_{tpi,out}$, then update the guesses for the outer loop variables as a convex combination governed by $\xi_{tpi}\in(0,1]$ of the respective initial guesses and the new implied values and repeat steps (3) through (5).
 
   $$
    &[\boldsymbol{r}_p^{i+1}, \boldsymbol{r}^{i+1}, \boldsymbol{\hat{w}}^{i+1}, \boldsymbol{p}^{i+1}, \boldsymbol{\hat{BQ}}^{i+1},\boldsymbol{\hat{TR}}^{i+1} ] = \\
@@ -395,9 +398,9 @@ The stationary non-steady state (transition path) solution algorithm has followi
 
 24. If the maximum absolute error among the M-1+5 outer loop error terms is less-than-or-equal-to some small positive tolerance $toler_{tpi,out}$ in each period along the transition path, $\max\big|\left(error_{r_p}, error_r, error_w, error_p, error_{bq},error_{tr}\right)\bigr| \leq toler_{tpi,out}$ then the non-steady-state equilibrium has been found.
 
-	1. Make sure that the resource constraint for industry $M$ (goods market clearing) {eq}`EqStnrzMarkClrGoods_M` is satisfied in each period along the time path. It is redundant, but this is a good check as to whether everything worked correctly.
-	2. Make sure that the government budget constraint {eq}`EqStnrzGovBC` binds.
-	3. Make sure that all the $(T+S)\times2JS$ household Euler equations are solved to a satisfactory tolerance.
+  1. Make sure that the resource constraint for industry $M$ (goods market clearing) {eq}`EqStnrzMarkClrGoods_M` is satisfied in each period along the time path. It is redundant, but this is a good check as to whether everything worked correctly.
+  2. Make sure that the government budget constraint {eq}`EqStnrzGovBC` binds.
+  3. Make sure that all the $(T+S)\times2JS$ household Euler equations are solved to a satisfactory tolerance.
 
 Under alternative model configurations, the solution algorithm changes slightly.  When `budget_balance = True`, the guess of $\boldsymbol{\hat{TR}}$ in the outer loop is replaced by the guess of $\boldsymbol{\hat{Y}}$ and transfers are determined a residual from the government budget constraint given revenues and other spending policy.  When `baseline_spending = True`, $\boldsymbol{\hat{TR}}$ is determined from the baseline model solution and not updated in the outer loop described above.  In this case $\boldsymbol{\hat{Y}}$ becomes variable that is updates in the outer loop.
 
diff --git a/docs/book/content/theory/financial.md b/docs/book/content/theory/financial.md
@@ -1,6 +1,5 @@
 
 (Chap_FinInt)=
-
 # Financial Intermediary
 
 Domestic household wealth $W^d_{t}=B_{t}$ and foreign ownership of domestic assets $W^f_{t}$, both in terms of the numeraire good, are invested in a financial intermediary. This intermediary purchases a portfolio of government bonds and private capital in accordance with the domestic and foreign investor demand for these assets and then returns a single portfolio rate of return to all investors.
@@ -15,7 +14,7 @@ Foreign demand for government bonds is specified in section {ref}`SecMarkClrMktC
 This leaves domestic investors to buy up the residual amount of government debt:
 
   ```{math}
-  :label: EqMarkClr_zetaD2
+  :label: EqMarkClr_DomesticDebt
     D^{d}_{t} = D_{t} - D^{f}_{t} \quad\forall t
   ```
 
diff --git a/docs/book/content/theory/government.md b/docs/book/content/theory/government.md
diff --git a/docs/book/content/theory/intro.md b/docs/book/content/theory/intro.md
diff --git a/ogcore/utils.py b/ogcore/utils.py
