Big documentation update

[rickecon]

This PR adds UBI directly to OG-USA. It also updates the documentation to reflect the default specification of the model. In particular, it adds r_hh to the documentation and includes the partially open economy as the default specification. The follow checklist gives the sections that I have gone through that I think are done.

• Model Overview
• Households
• FIrms
• Government
• Market Clearing
• Open Economy Options
• Stationarization
• Equilibrium
• Exogenous Parameters
• Calibration of Macroeconomic Parameters
• Demographics
• Lifetime Earnings Profiles
• Tax Functions
• Bequest Process Calibration
• Universal Basic Income

[rickecon]

My last commit finished a big update for all the documentation up through the steady-state equilibrium section of equilibrium.md. I re-did the description of the steady-state solution algorithm to match our default specification. I am going to leave the steady-state results section as a TODO for us to update later. To finish the equilibrium section of the documentation, I just need to go through the transition path description and make sure it is updated.

[rickecon]

@jdebacker said:

First sentence of “Calculating UBI” section: “UBI household transfers”

In the "UBI specification not adjusted for economic growth" section, there needs to be a space between "nonstationary" and "values" in first sentence of last paragraph. This whole sentence should be looked at, it could be compilation issues, but it seemed a bit jumbled.

I fixed the typo in the first section of the "Calculating UBI" section, and I rewrote the last paragraph of the "UBI specification not adjusted for economic growth" section to be two paragraphs with a new equation in between, plus a new footnote. They are the following:

[rickecon]

@jdebacker said:

UBI parameter names - do we want to make these consistent with Tax-Calculator where possible? Do we want to be able to read them in from a Tax-Calculator reform dictionary if they are specified there? This second question related to the first but is not relevant for documentation (it'd be handled in parameters.py, I think).

I don't know about this. Conceptually it is always nice to have OG-USA read parameters from Tax-Calculator or any other model. But:

1. OG-USA's UBI is a mutually exclusive substitute for whatever capability Tax-Calculator has to handle UBI. So I am trying to think of the use case for bringing those parameters in from Tax-Calculator.
2. We can always make a crosswalk from Tax-Calculator to OG-USA in parameters.py.
3. The Tax-Calculator UBI parameters are UBI_u18, UBI_1820, UBI_21, UBI_ecrt. These are a little different from the current OG-USA parameters in PR Add UBI policy parameters to OG-USA code #715.

My inclination is to keep these separate for now. But it would be straightforward to harmonize them in the future. @MaxGhenis signed off on the OG-USA parameters when I set them up.

[rickecon]

@jdebacker . I think I have addressed all your questions in the discussion above. Let me know what else you would like me to change for this to be merged. Thanks for the long review.

[MaxGhenis]

Yeah I don't think we can avoid the confusion here on parameters, but separate names from the taxcalc parameters seems like the right call IMO.

Will the UBI go in the OG-USA Parameters...Fiscal Policy Parameters section of Compute Studio, rather than Tax-Calculator Parameters?

[rickecon]

@MaxGhenis said:

Will the UBI go in the OG-USA Parameters...Fiscal Policy Parameters section of Compute Studio, rather than Tax-Calculator Parameters?

I haven't crossed that bridge yet. But I don't think it makes sense to put them in the Tax-Calculator parameters since they will not be Tax-Calculator parameters.

[jdebacker]

@rickecon Said:

I don't know about this. Conceptually it is always nice to have OG-USA read parameters from Tax-Calculator or any other model. But:
OG-USA's UBI is a mutually exclusive substitute for whatever capability Tax-Calculator has to handle UBI. So I am trying to think of the use case for bringing those parameters in from Tax-Calculator.

The use case would be the same as with taxes: one wants to get a detailed static revenue estimate and distributional analysis and so simulates a UBI in Tax-Calculator. Then one further wants to find the economic impacts of this plan and so runs the UBI program through OG-USA. By mapping parameters from Tax-Calculator into OG-USA, the user only needs to specify the parameters one time and it ensures consistency.

We can always make a crosswalk from Tax-Calculator to OG-USA in parameters.py.

This is a good point - we could do that. But we are starting from scratch now, so we can avoid having to do work later if we want.

The Tax-Calculator UBI parameters are UBI_u18, UBI_1820, UBI_21, UBI_ecrt. These are a little different from the current OG-USA parameters in PR #715.

Yes, but we could (in principle) add one more parameter for UBI for 18-20 year olds to OG-USA and a UBI for 65+ to Tax-Calculator. Seems like the latter would be a good addition to Tax-Calculator - kind of surprised it's not there. The UBI for 18-20 year olds in OG-USA could be tough to calibrate since they aren't economically active in the model at that age, but in the data there maybe many of that age in their own households (not dependents of their parents).

cc @MaxGhenis

My inclination is to keep these separate for now. But it would be straightforward to harmonize them in the future. @MaxGhenis signed off on the OG-USA parameters when I set them up.

[rickecon]

@MaxGhenis. Given your esteemed position as the head of the UBI Center, what parameters should we have in both Tax-Calculator and OG-USA?

[MaxGhenis]

Adding UBI_65 is blocked by a taxdata bug, see PSLmodels/Tax-Calculator#2469.

I think taxcalc split out 18-20-year-olds because AEI scholar Charles Murray's UBI plan is 21+, but all others I've seen have been 18+. If it complicates things in OG-USA it could be another reason to consider dropping it - I doubt it's been used much if at all.

The 0-17, 18-64, 65+ buckets are the right ones to start with IMO, and if any would be added next, it'd probably be splitting the child component into 0-5 and 6-17, to match US child allowance proposals and address differences in childcare needs by age.

[rickecon]

@jdebacker @MaxGhenis. I like the idea of changing the names of the variables and adding one extra:

• UBI_dol_017: dollar amount of UBI per year for each child (non-head of household and non-spouse of head of household) age 0-17 (under 18)
• UBI_dol_1820: dollar amount of UBI per year for each non-head of household and non-spouse of head of household age 18-20
• UBI_dol_2164: dollar amount of UBI for each adult ages 21 through 64
• UBI_dol_65p: dollar amount of UBI for each adult age 65 and over

These variables are much closer to the Tax-Calculator variable names. But I think it is important to have the "dol" descriptor in these OG-USA variable names to distinguish between the dollar unit inputs and the model units that are solved for in the steady-state solution. These variable names are also a little different than the Tax-Calculator names in some other dimensions that I think are better and more descriptive (e.g., "_017" rather than "_u18").

[rickecon]

@jdebacker . I just noticed that all the citation references in the text of the Jupyter Book documentation were broken (see Carroll reference on this page and any of the other references), and the References page at the end of the book does not populate. You'll also notice that the OG-USA Citations page does not populate.

I fixed the in-text citations and the References page by adding these two lines at the end of the _config.yml file:

bibtex_bibfiles:
   - OGUSA_references.bib

However, I still cannot get the Citations page to populate. Maybe we leave this Citations page issue to another PR.

[jdebacker]

These variables are much closer to the Tax-Calculator variable names. But I think it is important to have the "dol" descriptor in these OG-USA variable names to distinguish between the dollar unit inputs and the model units that are solved for in the steady-state solution. These variable names are also a little different than the Tax-Calculator names in some other dimensions that I think are better and more descriptive (e.g., "_017" rather than "_u18").

@rickecon I'd drop the "dol" here. When we switch this over to OG-MOD this will be confusing since some calibrations will use a different currency. Maybe some other name like "nominal"? Or just handle it in the description of the parameter in the parameters JSON file?

[rickecon]

@jdebacker . I like the _nom and _mod descriptors for "nominal" and "model" values, respectively. I think the distinction is important in the OG models where inputs are in nominal currency terms and internal values have to be converted to model units. So how do you feel about the following variables?

• UBI_nom_017: dollar (nominal) amount of UBI per year for each child (non-head of household and non-spouse of head of household) age 0-17 (under 18)
• UBI_nom_1820: dollar (nominal) amount of UBI per year for each non-head of household and non-spouse of head of household age 18-20
• UBI_nom_2164: dollar (nominal) amount of UBI for each adult ages 21 through 64
• UBI_nom_65p: dollar (nominal) amount of UBI for each adult age 65 and over

[rickecon]

I just pinned the version of Jupyter Book to v. 0.9.1 in the environment.yml file and recompiled the Jupyter Book. Now all the citations in the text are good, the references page compiles, and the citations page compiles--all the required behavior from Issue #717.

Now my question is how to make it work with Jupyter Book version 0.10.0. Maybe we have to add the citations.bib file to the bibtex_bibfiles: section at the end of _config.yml. @jdebacker

[jdebacker]

So how do you feel about the following variables?

I am good with those name. Thanks for thinking about this.

[rickecon]

I changed the environment.yml to be jupyter-book>=0.9.1. However, I still can't get the Citations page to compile under the Jupyter Book 0.10.1 or 0.10.0 versions. I tried the following two fixes with v. 0.10.1 in the _config.yml file, neither of which worked:

Fix attempt 1

bibtex_bibfiles:
   - OGUSA_references.bib
   - ../../citations.bib

Fix attempt 2, copying citations.md to same directory as OGUSA_references.bib

bibtex_bibfiles:
   - OGUSA_references.bib
   - citations.bib

I think we should move forward with this PR as it is, and work to fix the citations page in a future PR, following the Issue #717 thread.

[rickecon]

@jdebacker . I have now updated the UBI variable names according to the discussion above in UBI.md from the Calibration section of the documentation. I will update those variable names accordingly in PR #715.

[rickecon]

@jdebacker . I think I am done with all the fixes that will make it into this PR. This is ready for your (maybe) final review.

[rickecon]

@jdebacker . I don't know what I did, but the Jupyter Book v. 0.10.1 is now compiling the Citations page, with citations.bib not in the _config.yml file and located in the main OG-USA/ directory, and with no changes to citations.md. OK, now even better to go. Closing Issue #717.

[jdebacker]

@rickecon This looks great. Thanks for your hard work on this substantial update!