Missing aggregate pension outlays in theory documentation

[rickecon]

I think we are missing our specification of household social security income through the replacement rate and aggregate pension outlays in the theory documentation of our model, although it is correctly specified in the code. We need to update the documentation.

For example, the variable agg_pension_outlays shows up in the debt law of motion in the code in fiscal.py line 94, but it is not listed in the theoretical description in the documentation in equations (63) or the corresponding values in the closure rules (67), (68), or (69).

Also, the Tax-Calculator microsimulation model includes both the employee and employer portions of the payroll tax, which is therefore incorporated into the household's budget constraint through the tax functions. We model the social security payouts to retired households in OG-USA with the theta replacement rate parameter. However, this parameter and its calculation only shows up in the code (many places) and not in the documentation of the household.

cc: @jdebacker

[jdebacker]

@rickecon This is correct - the documentation is out of step with the code here.

When adding pension receipts to the household budget, I would suggest adding a general pension term (not the theta parameter used for modeling social security), similar to what we did with OG-ITA. Then a section/chapter on pension theory can outline the different types of pension systems (similar to what we do with tax functions). This way, we keep the theory more flexible to include adding different pension systems in the future.

[jdebacker]

These pensions equations have been added to the docs.