Merge pull request #129 from jdebacker/param_doc

Merging

docs/book/_toc.yml

@@ -9,14 +9,14 @@ parts:
   - file: content/api/public_api
 - caption: Calibration
   chapters:
-  - file: content/calibration/exogenous_parameters
   - file: content/calibration/macro
   - file: content/calibration/demographics
   - file: content/calibration/earnings
   - file: content/calibration/tax_functions
   - file: content/calibration/bequests
   - file: content/calibration/UBI
   - file: content/calibration/matching_lwi
+  - file: content/calibration/exogenous_parameters
 - caption: References
   chapters:
   - file: content/OGUSA_references

docs/book/content/calibration/exogenous_parameters.md

@@ -14,9 +14,8 @@ kernelspec:
 (Chap_Exog)=
 # Exogenous Parameters
 
-  [TODO: This chapter needs heavy updating. Would be nice to do something similar to API chapter. But it is also nice to have references and descriptions as in the table below.]
+  The JSON file [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/default_parameters.json) provides values for all the model parameters used as defaults for OG-USA. Below, we provide a table highlighting some of the parameters describing the scale of the model (number of periods, aged, productivity types) and some parameters of the solution method (dampening parameter for TPI). The table below provides a list of the exogenous parameters and their baseline calibration values.
 
-  In this chapter, list the exogenous inputs to the model, options, and where the values come from (weak calibration vs. strong calibration). Point to the respective chapters for some of the inputs. Mention the code in [`default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/default_parameters.json) and [`parameters.py`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/parameters.py).
 
   <!-- +++
   ```{code-cell} ogusa-dev
@@ -30,40 +29,76 @@ kernelspec:
   ```
   -->
 
-  ```{list-table} **List of exogenous parameters and baseline calibration values.**
-  :header-rows: 1
-  :name: TabExogVars
-  * - **Symbol**
-    - **Description**
-    - **Value**
-  * - $S$
-    - Maximum periods in economically active household life
-    - 80
-  * - $E$
-    - Number of periods of youth economically outside the model
-    - $\text{round} \frac{S}{4}$=20
-  * - $R$
-    - Retirement age (period)
-    - $E + \text{round} (\frac{9}{16} S) = 65$
-  * - $T_1$
-    - Number of periods to steady state for initial time path guesses
-    - 160
-  * - $T_2$
-    - Maximum number of periods to steady state for nonsteady-state equilibrium
-    - 160
-  * - $\nu$
-    - Dampening parameter for TPI
-    - 0.4
-  * - ${ \{ { \{ \omega_{s,0} \} }_{s=1}^{E+S}  \}}_{t=0}^{T_2 + S - 1}$
-    - Initial population distribution by age
-    - (see Chap. {ref}`Chap_Demog`)
-  * - ${ \{ f_s \}}_{s=1}^{E+S}$
-    - Fertility rates by age
-    - (see Sec. {ref}`SecDemogFert`)
-  * - ${ \{ i_s \}}_{s=1}^{E+S}$
-    - Immigration rates by age
-    - (see Sec. {ref}`SecDemogMort`)
-  * - ${ \{ \rho_s \}}_{s=0}^{E+S}$
-    - Mortality rates by age
-    - (see Sec. {ref}`SecDemogImm`)
-  ```
+  **List of exogenous parameters and baseline calibration values.**
+  | Symbol                           | Description                                                             | Value                                                 |
+|:---------------------------------|:------------------------------------------------------------------------|:------------------------------------------------------|
+| $\texttt{start_year}$           | Initial year                                                            | 2025                                                  |
+| $\omega_{s,t}$                   | Population by age over time                                             | Too large to report here, see default parameters JSON |
+| $i_{s,t}$                        | Immigration rates by age                                                | Too large to report here, see default parameters JSON |
+| $\rho_{s,t}$                     | Mortality rates by age                                                  | Too large to report here, see default parameters JSON |
+| $e_{j,s,t}$                      | Deterministic ability process                                           | Too large to report here, see default parameters JSON |
+| $\lambda_{j}$                    | Lifetime income group percentages                                       | Too large to report here, see default parameters JSON |
+| $J$                              | Number of lifetime income groups                                        | 10                                                    |
+| $S$                              | Maximum periods in economically active individual life                  | 80                                                    |
+| $E$                              | Number of periods of youth economically outside the model               | 20                                                    |
+| $T$                              | Number of periods to steady-state                                       | 320                                                   |
+| $R$                              | Retirement age                                                          | [65.000...65.000]                                     |
+| $\tilde{l}$                      | Maximum hours of labor supply                                           | 1.000                                                 |
+| $\beta$                          | Discount factor                                                         | [0.910...0.995]                                       |
+| $\sigma$                         | Coefficient of constant relative risk aversion                          | 1.500                                                 |
+| $\nu$                            | Frisch elasticity of labor supply                                       | 0.400                                                 |
+| $b$                              | Scale parameter in utility of leisure                                   | 0.573                                                 |
+| $\upsilon$                       | Shape parameter in utility of leisure                                   | 2.856                                                 |
+| $\chi^{n}_{s}$                   | Disutility of labor level parameters                                    | Too large to report here, see default parameters JSON |
+| $\chi^{b}_{j}$                   | Utility of bequests level parameters                                    | [80.000...80.000]                                     |
+| $\texttt{use_zeta}$             | Whether to distribute bequests between lifetime income groups           | 0.00E+00                                              |
+| $\zeta$                          | Distribution of bequests                                                | Too large to report here, see default parameters JSON |
+| $Z_{t}$                          | Total factor productivity                                               | Too large to report here, see default parameters JSON |
+| $\gamma$                         | Capital share of income                                                 | [0.380...0.380]                                       |
+| $\varepsilon$                    | Elasticity of substitution between capital and labor                    | [1.000...1.000]                                       |
+| $\delta$                         | Capital depreciation rate                                               | 0.050                                                 |
+| $g_{y}$                          | Growth rate of labor augmenting technological progress                  | 0.020                                                 |
+| $\texttt{tax_func_type}$       | Functional form used for income tax functions                           | DEP                                                   |
+| $\texttt{analytical_mtrs}$      | Whether use analytical MTRs or estimate MTRs                            | 0.00E+00                                              |
+| $\texttt{age_specific}$         | Whether use age-specific tax functions                                  | 1.000                                                 |
+| $\tau^{p}_{t}$                   | Payroll tax rate                                                        | [0.000...0.000]                                       |
+| $\tau^{BQ}_{t}$                  | Bequest (estate) tax rate                                               | [0.000...0.000]                                       |
+| $\tau^{b}_{t}$                   | Entity-level business income tax rate                                   | Too large to report here, see default parameters JSON |
+| $\delta^{\tau}_{t}$              | Rate of depreciation for tax purposes                                   | Too large to report here, see default parameters JSON |
+| $\tau^{c}_{t,s,j}$               | Consumption tax rates                                                   | Too large to report here, see default parameters JSON |
+| $H$                              | Coefficient on linear term in wealth tax function                       | [0.100...0.100]                                       |
+| $M$                              | Constant in wealth tax function                                         | [1.000...1.000]                                       |
+| $P$                              | Coefficient on level term in wealth tax function                        | [0.000...0.000]                                       |
+| $\texttt{budget_balance}$       | Whether have a balanced budget in each period                           | 0.00E+00                                              |
+| $\texttt{baseline_spending}$    | Whether level of spending constant between the baseline and reform runs | 0.00E+00                                              |
+| $\alpha^{T}_{t}$                 | Transfers as a share of GDP                                             | [0.052...0.052]                                       |
+| $\eta_{j,s,t}$                   | Distribution of transfers                                               | Too large to report here, see default parameters JSON |
+| $\eta_{RM,j,s,t}$                | Distribution of remittances                                             | Too large to report here, see default parameters JSON |
+| $\alpha^{G}_{t}$                 | Government spending as a share of GDP                                   | [0.091...0.091]                                       |
+| $\alpha_{RM,1}$                  | Remittances as a share of GDP in initial period                         | 0.00E+00                                              |
+| $\alpha_{RM,T}$                  | Remittances as a share of GDP in long run                               | 0.00E+00                                              |
+| $g_{RM,t}$                       | Growth rate of remittances in initial periods                           | [0.000...0.000]                                       |
+| $t_{G1}$                         | Model period in which budget closure rule starts                        | 20                                                    |
+| $t_{G2}$                         | Model period in which budget closure rule ends                          | 256                                                   |
+| $\rho_{G}$                       | Budget closure rule smoothing parameter                                 | 0.100                                                 |
+| $\bar{\alpha}_{D}$               | Steady-state Debt-to-GDP ratio                                          | 2.000                                                 |
+| $\alpha_{D,0}$                   | Initial period Debt-to-GDP ratio                                        | 0.990                                                 |
+| $\tau_{d,t}$                     | Scale parameter in government interest rate wedge                       | [0.000...0.000]                                       |
+| $\mu_{d,t}$                      | Shift parameter in government interest rate wedge                       | [-0.005...-0.010]                                     |
+| $\texttt{avg_earn_num_years}$ | Number of years over which compute average earnings for pension benefit | 35                                                    |
+| $\texttt{AIME_bkt_1}$          | First AIME bracket threshold                                            | 1174.000                                              |
+| $\texttt{AIME_bkt_2}$          | Second AIME bracket threshold                                           | 7078.000                                              |
+| $\texttt{PIA_rate_bkt_1}$     | First AIME bracket PIA rate                                             | 0.900                                                 |
+| $\texttt{PIA_rate_bkt_2}$     | Second AIME bracket PIA rate                                            | 0.320                                                 |
+| $\texttt{PIA_rate_bkt_3}$     | Third AIME bracket PIA rate                                             | 0.150                                                 |
+| $\texttt{PIA_maxpayment}$       | Maximum PIA payment                                                     | 4555.000                                              |
+| $\texttt{PIA_minpayment}$       | Minimum PIA payment                                                     | 0.00E+00                                              |
+| $\theta_{adj,t}$                 | Adjustment to replacement rate                                          | [1.000...1.000]                                       |
+| $r^{*}_{t}$                      | World interest rate                                                     | [0.040...0.040]                                       |
+| $D_{f,0}$                        | Share of government debt held by foreigners in initial period           | 0.400                                                 |
+| $\zeta_{D, t}$                   | Share of new debt issues purchased by foreigners                        | [0.400...0.400]                                       |
+| $\zeta_{K, t}$                   | Share of excess capital demand satisfied by foreigners                  | [0.500...0.500]                                       |
+| $\xi$                            | Dampening parameter for TPI                                             | 0.400                                                 |
+| $\texttt{maxiter}$               | Maximum number of iterations for TPI                                    | 250                                                   |
+| $\texttt{mindist_SS}$           | SS solution tolerance                                                   | 1.00E-09                                              |
+| $\texttt{mindist_TPI}$          | TPI solution tolerance                                                  | 1.00E-05                                              |

docs/create_doc_figures.py

@@ -0,0 +1,164 @@
+"""
+This script creates tables and figures from the OG-USA documentation.
+"""
+
+# import
+import os
+import numpy as np
+import matplotlib.pyplot as plt
+import importlib
+import json
+import ogcore
+from ogcore.parameters import Specifications
+from ogcore import parameter_plots as pp
+from ogcore import demographics as demog
+import ogusa
+
+
+CUR_DIR = os.path.dirname(os.path.realpath(__file__))
+UN_COUNTRY_CODE = "840"
+plot_path = os.path.join(CUR_DIR, "book", "content", "calibration", "images")
+YEAR_TO_PLOT = 2025
+# update path for demographics graphdiag plots
+demog.OUTPUT_DIR = plot_path
+
+# Use a custom matplotlib style file for plots
+plt.style.use("ogcore.OGcorePlots")
+
+"""
+Load specifications object with default parameters
+"""
+p = Specifications()
+with importlib.resources.open_text(
+    "ogusa", "ogusa_default_parameters.json"
+) as file:
+    defaults = json.load(file)
+p.start_year = YEAR_TO_PLOT
+p.update_specifications(defaults)
+
+"""
+Demographics chapter
+"""
+# Fertility rates
+fert_rates, fig = demog.get_fert(
+    totpers=100,
+    min_age=0,
+    max_age=99,
+    country_id=UN_COUNTRY_CODE,
+    start_year=YEAR_TO_PLOT,
+    end_year=YEAR_TO_PLOT,
+    graph=True,
+    plot_path=None,
+    download_path=None,
+)
+plt.savefig(os.path.join(plot_path, "fert_rates.png"), dpi=300)
+# Mortality rates
+mort_rates, _, fig = demog.get_mort(
+    totpers=100,
+    min_age=0,
+    max_age=99,
+    country_id=UN_COUNTRY_CODE,
+    start_year=YEAR_TO_PLOT,
+    end_year=YEAR_TO_PLOT,
+    graph=True,
+    plot_path=None,
+    download_path=None,
+)
+plt.xlabel(r"Age ($s$)")
+plt.ylabel(r"Mortality rate ($\rho_s$)")
+plt.savefig(os.path.join(plot_path, "mort_rates.png"), dpi=300)
+# Immigration rates
+imm_rates, fig = demog.get_imm_rates(
+    totpers=100,
+    min_age=0,
+    max_age=99,
+    fert_rates=None,
+    mort_rates=None,
+    infmort_rates=None,
+    pop_dist=None,
+    country_id=UN_COUNTRY_CODE,
+    start_year=YEAR_TO_PLOT,
+    end_year=YEAR_TO_PLOT + 50,
+    graph=True,
+    plot_path=None,
+    download_path=None,
+)
+plt.xlabel(r"Age ($s$)")
+plt.ylabel(r"Immigration rate ($i_s$)")
+# give a little more before the plot source note
+
+plt.savefig(os.path.join(plot_path, "imm_rates.png"), dpi=300)
+# Fixed versus original population distribution
+demog.get_pop_objs(
+    E=20,
+    S=80,
+    T=320,
+    min_age=0,
+    max_age=99,
+    fert_rates=None,
+    mort_rates=None,
+    infmort_rates=None,
+    imm_rates=None,
+    infer_pop=False,
+    pop_dist=None,
+    pre_pop_dist=None,
+    country_id=UN_COUNTRY_CODE,
+    initial_data_year=YEAR_TO_PLOT - 1,
+    final_data_year=YEAR_TO_PLOT + 2,
+    GraphDiag=True,
+    download_path=None,
+)
+
+
+# Population growth
+fig = pp.plot_pop_growth(
+    p,
+    start_year=YEAR_TO_PLOT,
+    num_years_to_plot=150,
+    include_title=False,
+    path=None,
+)
+# Add average growth rate with this
+plt.plot(
+    np.arange(YEAR_TO_PLOT, YEAR_TO_PLOT + 150),
+    np.ones(150) * np.mean(p.g_n[:150]),
+    linestyle="-",
+    linewidth=1,
+    color="red",
+)
+plt.xlabel(r"Model Period ($t$)")
+plt.ylabel(r"Population Growth Rate ($g_{n,t}$)")
+plt.savefig(os.path.join(plot_path, "population_growth_rates.png"), dpi=300)
+
+# Population distribution at different points in time
+pp.plot_population(
+    p,
+    years_to_plot=[
+        YEAR_TO_PLOT,
+        YEAR_TO_PLOT + 25,
+        YEAR_TO_PLOT + 50,
+        YEAR_TO_PLOT + 100,
+    ],
+    include_title=False,
+    path=plot_path,
+)
+"""
+Income chapter
+"""
+# USA profiles
+pp.plot_ability_profiles(
+    p, p2=None, t=None, log_scale=True, include_title=False, path=plot_path
+)
+
+
+"""
+Create table for exogenous parameters
+"""
+import ogcore.parameter_tables as pt
+from ogcore import Specifications
+
+table = pt.param_table(
+    p,
+    table_format="md",
+    path=os.path.join(plot_path, "exogenous_parameters_table.md"),
+)