From 808e409945eb0ebea63e30b6e63d99dbd7dda720 Mon Sep 17 00:00:00 2001
From: Richard Evans <rickecon@gmail.com>
Date: Fri, 26 Jul 2024 01:16:53 -0600
Subject: [PATCH] Changed OG-USA refs in docs to OG-ZAF

---
 docs/book/content/calibration/UBI.md          | 10 +++----
 .../calibration/exogenous_parameters.md       |  2 +-
 .../book/content/calibration/tax_functions.md | 28 +++++++++----------
 3 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/docs/book/content/calibration/UBI.md b/docs/book/content/calibration/UBI.md
index 6045647..38dc7f6 100644
--- a/docs/book/content/calibration/UBI.md
+++ b/docs/book/content/calibration/UBI.md
@@ -3,15 +3,15 @@
 
 [TODO: This section is far along but needs to be updated.]
 
-We have included the modeling of a universal basic income (UBI) policy directly in the theory and code for [`OG-Core`] on which dependency the `OG-USA` is based. UBI shows up in the household budget constraint {eq}`EqHHBC`, and is described in the [Budget Constraint](https://pslmodels.github.io/OG-Core/content/theory/households.html#budget-constraint) section of the Households chapter of the `OG-Core` documentation. We calculate the time series of a UBI matrix $ubi_{j,s,t}$ representing the UBI transfer to every household with head of household age $s$, lifetime income group $j$, in period $t$. We calculate the time series of this matrix from five parameters and some household composition data that we impose upon the existing demographics of `OG-USA`.
+We have included the modeling of a universal basic income (UBI) policy directly in the theory and code for [`OG-Core`] on which dependency the `OG-ZAF` is based. UBI shows up in the household budget constraint {eq}`EqHHBC`, and is described in the [Budget Constraint](https://pslmodels.github.io/OG-Core/content/theory/households.html#budget-constraint) section of the Households chapter of the `OG-Core` documentation. We calculate the time series of a UBI matrix $ubi_{j,s,t}$ representing the UBI transfer to every household with head of household age $s$, lifetime income group $j$, in period $t$. We calculate the time series of this matrix from five parameters and some household composition data that we impose upon the existing demographics of `OG-ZAF`.
 
 
 (SecUBIcalc)=
 ## Calculating UBI
 
-  We calculate the time series of UBI household transfers in model units $ubi_{j,s,t)}$ and the time series of total UBI expenditures in model units $UBI_t$ from five parameters described in the [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/ogusa_default_parameters.json) file (`ubi_growthadj`, `ubi_nom_017`, `ubi_nom_1864`, `ubi_nom_65p`, and `ubi_nom_max`) interfaced with the `OG-USA` demographic dynamics over lifetime income groups $j$ and ages $s$, and multiplied by household composition matrices from the `Calibrate` class of the `OG-USA/ogusa/calibrate.py` module in the repository.
+  We calculate the time series of UBI household transfers in model units $ubi_{j,s,t)}$ and the time series of total UBI expenditures in model units $UBI_t$ from five parameters described in the [`ogzaf_default_parameters.json`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/ogzaf_default_parameters.json) file (`ubi_growthadj`, `ubi_nom_017`, `ubi_nom_1864`, `ubi_nom_65p`, and `ubi_nom_max`) interfaced with the `OG-ZAF` demographic dynamics over lifetime income groups $j$ and ages $s$, and multiplied by household composition matrices from the `Calibrate` class of the `OG-ZAF/ogzaf/calibrate.py` module in the repository.
 
-  From the [OG-USA](https://github.com/PSLmodels/OG-USA) repository, we have four $S\times J$ matrices `ubi_num_017_mat`$_{j,s}$, `ubi_num_1864_mat`$_{j,s}$, and `ubi_num_65p_mat`$_{j,s}$ representing the number of children under age 0-17, number of adults ages 18-64, and the number of seniors age 65 and over, respectively, by lifetime ability group $j$ and age $s$ of head of household. Because our demographic age data match up well with head-of-household data from other datasets, we do not have to adjust the values in these matrices.[^HOH_age_dist_note]
+  From the [OG-ZAF](https://github.com/EAPD-DRB/OG-ZAF) repository, we have four $S\times J$ matrices `ubi_num_017_mat`$_{j,s}$, `ubi_num_1864_mat`$_{j,s}$, and `ubi_num_65p_mat`$_{j,s}$ representing the number of children under age 0-17, number of adults ages 18-64, and the number of seniors age 65 and over, respectively, by lifetime ability group $j$ and age $s$ of head of household. Because our demographic age data match up well with head-of-household data from other datasets, we do not have to adjust the values in these matrices.[^HOH_age_dist_note]
 
   Now we can solve for the dollar-valued (as opposed to model-unit-valued) UBI transfer to each household in the first period $ubi^{\$}_{j,s,t=0}$ in the following way. Let the parameter `ubi_nom_017` be the dollar value of the UBI transfer to each household per dependent child age 17 and under. Let the parameter `ubi_nom_1864` be the dollar value of the UBI transfer to each household per adult between the ages of 18 and 64. Let `ubi_nom_65p` be the dollar value of UBI transfer to each household per senior 65 and over. And let `ubi_nom_max` be the maximum UBI benefit per household.
 
@@ -57,6 +57,6 @@ We have included the modeling of a universal basic income (UBI) policy directly
 (SecUBIfootnotes)=
 ## Footnotes
 
-[^HOH_age_dist_note]: DeBacker and Evans compared the `OG-USA` age demographics $\hat{\omega}_{s,t}$ with the respective age demographics in Tax Policy Center's microsimulation model and in [Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator)'s microsimulation model. The latter two microsimulation models' age demographics are based on head of household tax filer age distributions, whereas `OG-USA`'s demographics are based on the population age distribution.
+[^HOH_age_dist_note]: DeBacker and Evans compared the `OG-ZAF` age demographics $\hat{\omega}_{s,t}$ with the respective age demographics in Tax Policy Center's microsimulation model and in [Tax-Calculator](https://github.com/PSLmodels/Tax-Calculator)'s microsimulation model. The latter two microsimulation models' age demographics are based on head of household tax filer age distributions, whereas `OG-ZAF`'s demographics are based on the population age distribution.
 
-[^GrowthAdj_note]: We impose this requirement of `ubi_growthadj = False` when `g_y_annual < 0` in the [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/ogusa_default_parameters.json) "validators" specification of the parameter.
+[^GrowthAdj_note]: We impose this requirement of `ubi_growthadj = False` when `g_y_annual < 0` in the [`ogzaf_default_parameters.json`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/ogzaf_default_parameters.json) "validators" specification of the parameter.
diff --git a/docs/book/content/calibration/exogenous_parameters.md b/docs/book/content/calibration/exogenous_parameters.md
index 5e3e08a..a82a2a3 100644
--- a/docs/book/content/calibration/exogenous_parameters.md
+++ b/docs/book/content/calibration/exogenous_parameters.md
@@ -16,7 +16,7 @@ kernelspec:
 
   [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.]
 
-  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).
+  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 [`ogzaf_default_parameters.json`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/ogzaf_default_parameters.json) in the OG-ZAF repository and in [`default_parameters.json`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/default_parameters.json) and [`parameters.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/parameters.py) in the OG-Core repository.
 
   <!-- +++
   ```{code-cell} ogzaf-dev
diff --git a/docs/book/content/calibration/tax_functions.md b/docs/book/content/calibration/tax_functions.md
index 81dd294..549bb0d 100644
--- a/docs/book/content/calibration/tax_functions.md
+++ b/docs/book/content/calibration/tax_functions.md
@@ -1,9 +1,9 @@
 (Chap_TaxCalc)=
 # Tax Functions
 
-The government is not an optimizing agent in `OG-USA`. The government levies taxes on households, provides transfers to households, levies taxes on firms, spends resources on public goods, and makes rule-based adjustments to stabilize the economy in the long-run. The government can run budget deficits or surpluses in a given year and must, therefore, be able to accumulate debt or savings.
+The government is not an optimizing agent in `OG-ZAF`. The government levies taxes on households, provides transfers to households, levies taxes on firms, spends resources on public goods, and makes rule-based adjustments to stabilize the economy in the long-run. The government can run budget deficits or surpluses in a given year and must, therefore, be able to accumulate debt or savings.
 
-The government sector influences households through two terms in the household budget constraint {eq}`EqHHBC`---government transfers $TR_{t}$ and through the total tax liability function $T_{s,t}$, which can be decomposed into the effective tax rate times total income {eq}`EqTaxCalcLiabETR2`. In this chapter, we detail the household tax component of government activity $T_{s,t}$ in `OG-USA`, along with our method of incorporating detailed microsimulation data into a dynamic general equilibrium model.
+The government sector influences households through two terms in the household budget constraint {eq}`EqHHBC`---government transfers $TR_{t}$ and through the total tax liability function $T_{s,t}$, which can be decomposed into the effective tax rate times total income {eq}`EqTaxCalcLiabETR2`. In this chapter, we detail the household tax component of government activity $T_{s,t}$ in `OG-ZAF`, along with our method of incorporating detailed microsimulation data into a dynamic general equilibrium model.
 
 ```{math}
 :label: EqHHBC
@@ -16,12 +16,12 @@ Incorporating realistic tax and incentive detail into a general equilibrium mode
 
 The second difficulty in modeling realistic tax and incentive detail is the need for good microeconomic data on the individuals who make up the economy from which to simulate behavioral responses and corresponding tax liabilities and tax rates.
 
-`OG-USA` follows the method of {cite}`DeBackerEtAl:2019` of generating detailed tax data on effective tax rates and marginal tax rates for a sample of tax filers along with their respective income and demographic characteristics and then using that data to estimate parametric tax functions that can be incorporated into `OG-USA`.
+`OG-ZAF` follows the method of {cite}`DeBackerEtAl:2019` of generating detailed tax data on effective tax rates and marginal tax rates for a sample of tax filers along with their respective income and demographic characteristics and then using that data to estimate parametric tax functions that can be incorporated into `OG-ZAF`.
 
 (SecTaxCalcRateTheory)=
 ## Effective and Marginal Tax Rates
 
-  Before going into more detail regarding how we handle these two difficulties in `OG-USA`, we need to define some functions and make some notation. For notational simplicity, we will use the variable $x$ to summarize labor income, and we will use the variable $y$ to summarize capital income.
+  Before going into more detail regarding how we handle these two difficulties in `OG-ZAF`, we need to define some functions and make some notation. For notational simplicity, we will use the variable $x$ to summarize labor income, and we will use the variable $y$ to summarize capital income.
 
   ```{math}
   :label: EqTaxCalcLabInc
@@ -41,7 +41,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need
 
   Rearranging {eq}`EqTaxCalcLiabETR2` gives the definition of an effective tax rate ($ETR$) as total tax liability divided by unadjusted gross income, or rather, total tax liability as a percent of unadjusted gross income.
 
-  A marginal tax rate ($MTR$) is defined as the change in total tax liability from a small change income. In `OG-USA`, we differentiate between the marginal tax rate on labor income ($MTRx$) and the marginal tax rate on capital income ($MTRy$).
+  A marginal tax rate ($MTR$) is defined as the change in total tax liability from a small change income. In `OG-ZAF`, we differentiate between the marginal tax rate on labor income ($MTRx$) and the marginal tax rate on capital income ($MTRy$).
 
   ```{math}
   :label: EqTaxCalcMTRx
@@ -67,11 +67,11 @@ The second difficulty in modeling realistic tax and incentive detail is the need
 (SecTaxCalcMicro)=
 ## Microeconomic Data
 
-  For `OG-USA`, we use an open source microsimulation model called `Tax-Calculator` that uses microeconomic data on U.S. households from the Internal Revenue Service (IRS) Statistics of Income (SOI) Public Use File (PUF).[^taxcalc_note]  For users that have not paid for access to the Public Use File (PUF), `Tax-Calculator` has an option to use a CPS matched dataset that is publicly available free of charge that has the same general properties as the PUF.
+  For `OG-ZAF`, we use an open source microsimulation model called `Tax-Calculator` that uses microeconomic data on U.S. households from the Internal Revenue Service (IRS) Statistics of Income (SOI) Public Use File (PUF).[^taxcalc_note]  For users that have not paid for access to the Public Use File (PUF), `Tax-Calculator` has an option to use a CPS matched dataset that is publicly available free of charge that has the same general properties as the PUF.
 
-  `Tax-Calculator` starts with the underlying population microeconomic data, in which each observation is a filer with a population weight that renders the sample representative. It then processes the relevant income and demographic characteristics in order to calculate the tax liability of each individual, according to all the rich tax law of the United States tax code. `Tax-Calculator` can then calculate effective tax rates for all of these individuals, thereby creating a sample of how ETR's are related to other variables in our `OG-USA` model, such as total income $x + y$, labor income $x$, and capital income $y$. `Tax-Calculator` can also generate marginal tax rates by adding a dollar to each filer's income of a particular type and calculate how the filer's tax liability changes. This is a finite difference calculation of a derivative.
+  `Tax-Calculator` starts with the underlying population microeconomic data, in which each observation is a filer with a population weight that renders the sample representative. It then processes the relevant income and demographic characteristics in order to calculate the tax liability of each individual, according to all the rich tax law of the United States tax code. `Tax-Calculator` can then calculate effective tax rates for all of these individuals, thereby creating a sample of how ETR's are related to other variables in our `OG-ZAF` model, such as total income $x + y$, labor income $x$, and capital income $y$. `Tax-Calculator` can also generate marginal tax rates by adding a dollar to each filer's income of a particular type and calculate how the filer's tax liability changes. This is a finite difference calculation of a derivative.
 
-  {numref}`Figure %s <FigTaxCalcETRtotinc>` shows a scatter plot of $ETR$'s for 43-year-olds in 2017 and unadjusted gross income $x + y$. It is clear that $ETR$ is positively related to income. It is also clear that a significant number of filers have a negative $ETR$. We will discuss in Section {ref}`SecTaxCalcFuncs` the functional form `OG-USA` uses to best capture the main characteristics of these ETR data.
+  {numref}`Figure %s <FigTaxCalcETRtotinc>` shows a scatter plot of $ETR$'s for 43-year-olds in 2017 and unadjusted gross income $x + y$. It is clear that $ETR$ is positively related to income. It is also clear that a significant number of filers have a negative $ETR$. We will discuss in Section {ref}`SecTaxCalcFuncs` the functional form `OG-ZAF` uses to best capture the main characteristics of these ETR data.
 
   ```{figure} ./images/Compare_ETR_functions.png
   ---
@@ -101,7 +101,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need
 (SecTaxCalcFuncs_DEP)=
 ### Default Tax Functional Form
 
-  For the default option, `OG-USA` follows the approach of {cite}`DeBackerEtAl:2019` in using the following functional form to estimate tax functions for each age $s=E+1, E+2, ... E+S$ in each time period $t$. This option can be manually selected by setting the parameter `tax_func_type="DEP"`. Alternative specifications are outlined in Section {ref}`SecTaxCalcFuncs_Alt` below. Equation {eq}`EqTaxCalcTaxFuncForm` is written as a generic tax rate, but we use this same functional form for $ETR$'s, $MTRx$'s, and $MTRy$'s.
+  For the default option, `OG-ZAF` follows the approach of {cite}`DeBackerEtAl:2019` in using the following functional form to estimate tax functions for each age $s=E+1, E+2, ... E+S$ in each time period $t$. This option can be manually selected by setting the parameter `tax_func_type="DEP"`. Alternative specifications are outlined in Section {ref}`SecTaxCalcFuncs_Alt` below. Equation {eq}`EqTaxCalcTaxFuncForm` is written as a generic tax rate, but we use this same functional form for $ETR$'s, $MTRx$'s, and $MTRy$'s.
   ```{math}
   :label: EqTaxCalcTaxFuncForm
     \tau(x,y) = &\Bigl[\tau(x) + shift_x\Bigr]^\phi\Bigl[\tau(y) + shift_y\Bigr]^{1-\phi} + shift \\
@@ -240,15 +240,15 @@ The second difficulty in modeling realistic tax and incentive detail is the need
 
   The underlying data can limit the number of tax functions that can be estimated. For example, we use the age of the primary filer from the PUF-CPS match to be equivalent to the age of the DGE model household. The DGE model we use allows for individuals up to age 100, however the data contain few primary filers with age above age 80. Because we cannot reliably estimate tax functions for $s>80$, we apply the tax function estimates for 80 year-olds to those with model ages 81 to 100. In the case certain ages below age 80 have too few observations to enable precise estimation of the model parameters, we use a linear interpolation method to find the values for those ages $21\leq s <80$ that cannot be precisely estimated. [^interpolation_note]
 
-  In `OG-USA`, we estimate the 12-parameter functional form {eq}`EqTaxCalcTaxFuncForm` using weighted nonlinear least squares to fit an effective tax rate function $(\tau^{etr}_{s,t})$, a marginal tax rate of labor income function $(\tau^{mtrx}_{s,t})$, and a marginal tax rate of capital income function $(\tau^{mtry}_{s,t})$ for each age $E+1\leq s\leq E+S$ and each of the first 10 years from the current period. [^param_note] That means we have to perform 2,400 estimations of 12 parameters each. {numref}`Figure %s <FigTaxCalc3DvsPred>` shows the predicted surfaces for $\tau^{etr}_{s=42,t=2017}$, $\tau^{mtrx}_{s=42,t=2017}$, and $\tau^{mtry}_{s=42,t=2017}$ along with the underlying scatter plot data from which those functions were estimated. {numref}`TabTaxCalcEst42` shows the estimated values of those functional forms.
+  In `OG-ZAF`, we estimate the 12-parameter functional form {eq}`EqTaxCalcTaxFuncForm` using weighted nonlinear least squares to fit an effective tax rate function $(\tau^{etr}_{s,t})$, a marginal tax rate of labor income function $(\tau^{mtrx}_{s,t})$, and a marginal tax rate of capital income function $(\tau^{mtry}_{s,t})$ for each age $E+1\leq s\leq E+S$ and each of the first 10 years from the current period. [^param_note] That means we have to perform 2,400 estimations of 12 parameters each. {numref}`Figure %s <FigTaxCalc3DvsPred>` shows the predicted surfaces for $\tau^{etr}_{s=42,t=2017}$, $\tau^{mtrx}_{s=42,t=2017}$, and $\tau^{mtry}_{s=42,t=2017}$ along with the underlying scatter plot data from which those functions were estimated. {numref}`TabTaxCalcEst42` shows the estimated values of those functional forms.
 
-  The full set of estimated values are calculated using the [`get_tax_function_parameters`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/calibrate.py#L82) method of the [`Calibration`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/calibrate.py#L20) class  of the [`OG-USA/ogusa/calibrate.py`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/calibrate.py#L20) module. And the estimated baseline values are stored in the [`ogusa_default_parameters.json`](https://github.com/PSLmodels/OG-USA/blob/master/ogusa/ogusa_default_parameters.json) file.
+  The full set of estimated values are calculated using the [`get_tax_function_parameters`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/calibrate.py#L82) method of the [`Calibration`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/calibrate.py#L20) class  of the [`OG-ZAF/ogzaf/calibrate.py`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/calibrate.py#L20) module. And the estimated baseline values are stored in the [`ogzaf_default_parameters.json`](https://github.com/EAPD-DRB/OG-ZAF/blob/master/ogzaf/ogzaf_default_parameters.json) file.
 
 
 (SecTaxCalcFuncs_Alt)=
 ### Alternative Functional Forms
 
-  In addition to the default option using tax functions of the form developed by {cite}`DeBackerEtAl:2019`, `OG-USA` also allows users to specify alternative tax functions.  Three alternatives are offered:
+  In addition to the default option using tax functions of the form developed by {cite}`DeBackerEtAl:2019`, `OG-ZAF` also allows users to specify alternative tax functions.  Three alternatives are offered:
 
   1. Functions as in {cite}`DeBackerEtAl:2019`, but where $\tau^{etr}_{s,t}$, $\tau^{mtrx}_{s,t}$, and $\tau^{mtry}_{s,t}$ are functions of total income (i.e., $x+y$) and not labor and capital income separately.  Users can select this option by setting the parameter `tax_func_type="DEP_totalinc"`.
 
@@ -267,7 +267,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need
 (SecTaxCalcFactor)=
 ## Factor Transforming Income Units
 
-  The tax functions $\tau^{etr}_{s,t}$, $\tau^{mtrx}_{s,t}$, and $\tau^{mtry}_{s,t}$ are estimated based on current U.S. tax filer reported incomes in dollars. However, the consumption units of the `OG-USA` model are not in the same units as the real-world U.S. incomes data. For this reason, we have to transform the income by a $factor$ so that it is in the same units as the income data on which the tax functions were estimated.
+  The tax functions $\tau^{etr}_{s,t}$, $\tau^{mtrx}_{s,t}$, and $\tau^{mtry}_{s,t}$ are estimated based on current U.S. tax filer reported incomes in dollars. However, the consumption units of the `OG-ZAF` model are not in the same units as the real-world U.S. incomes data. For this reason, we have to transform the income by a $factor$ so that it is in the same units as the income data on which the tax functions were estimated.
 
   The tax rate functions are each functions of capital income and labor income $\tau(x,y)$. In order to make the tax functions return accurate tax rates associated with the correct levels of income, we multiply the model income $x^m$ and $y^m$ by a $factor$ so that they are in the same units as the real-world U.S. income data $\tau(factor\times x^m, factor\times y^m)$. We define the $factor$ such that average steady-state household total income in the model times the $factor$ equals the U.S. data average total income.
 
@@ -281,7 +281,7 @@ The second difficulty in modeling realistic tax and incentive detail is the need
 (SecTaxCalcTfers)=
 ## Household Transfers
 
-  Total transfers to households by the government in a given period $t$ is $TR_t$. The percent of those transfers given to all households of age $s$ and lifetime income group $j$ is $\eta_{j,s}$ such that $\sum_{s=E+1}^{E+S}\sum_{j=1}^J\eta_{j,s,t}=1$. `OG-USA` currently has the transfer distribution function set to distribute transfers uniformly among the population.
+  Total transfers to households by the government in a given period $t$ is $TR_t$. The percent of those transfers given to all households of age $s$ and lifetime income group $j$ is $\eta_{j,s}$ such that $\sum_{s=E+1}^{E+S}\sum_{j=1}^J\eta_{j,s,t}=1$. `OG-ZAF` currently has the transfer distribution function set to distribute transfers uniformly among the population.
 
   ```{math}
   :label: EqTaxCalcEtajs