Create a demographics module in OG-Core

[jdebacker]

This PR creates a demographic module in OG-Core. Such a module exists in the various country calibration repositories, but since all of those now use the UN population data, much of the code is repeated. Thus, moving the module here will remove redundant code across these country-specific repos.

In addition to this, the PR will add the following functionality:

1. The ability for users to use the time-varying forecasts from the UN WPP, up to a user-specified end date (or the maximum date available from the UN).
2. Users can enter their own custom forecasts of fertility, mortality, and immigration rates.
3. Users can enter their own estimate of the initial population distribution (Note that doing 2 and 3 together will bypass the use of UN data and use demographics.py purely for filling out demographic variables over the transition path and in the SS).
4. A country code parameter to specify which country's forecast to pull from the UN data.
5. Streamlines the plotting utilities and allows users to return a Matplotlib figure object (not just save a plot image file to disk).

[codecov-commenter]

Codecov Report

Attention: 54 lines in your changes are missing coverage. Please review.

Comparison is base (4b894bd) 80.26% compared to head (974eac0) 80.38%.

Additional details and impacted files

[](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels) ```diff @@ Coverage Diff @@ ## master #896 +/- ## ========================================== + Coverage 80.26% 80.38% +0.11% ========================================== Files 18 19 +1 Lines 4175 4445 +270 ========================================== + Hits 3351 3573 +222 - Misses 824 872 +48 ``` | [Flag](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels) | Coverage Δ | | |---|---|---| | [unittests](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels) | `80.38% <83.58%> (+0.11%)` | :arrow_up: | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#carryforward-flags-in-the-pull-request-comment) to find out more. | [Files](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels) | Coverage Δ | | |---|---|---| | [ogcore/SS.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL1NTLnB5) | `87.58% <ø> (-0.09%)` | :arrow_down: | | [ogcore/\_\_init\_\_.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL19faW5pdF9fLnB5) | `100.00% <ø> (ø)` | | | [ogcore/elliptical\_u\_est.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL2VsbGlwdGljYWxfdV9lc3QucHk=) | `100.00% <ø> (ø)` | | | [ogcore/execute.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL2V4ZWN1dGUucHk=) | `15.78% <ø> (ø)` | | | [ogcore/utils.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL3V0aWxzLnB5) | `88.35% <100.00%> (+0.44%)` | :arrow_up: | | [ogcore/firm.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL2Zpcm0ucHk=) | `97.35% <75.00%> (ø)` | | | [ogcore/parameter\_plots.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL3BhcmFtZXRlcl9wbG90cy5weQ==) | `80.86% <95.91%> (ø)` | | | [ogcore/txfunc.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL3R4ZnVuYy5weQ==) | `29.52% <0.00%> (ø)` | | | [ogcore/demographics.py](https://app.codecov.io/gh/PSLmodels/OG-Core/pull/896?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=PSLmodels#diff-b2djb3JlL2RlbW9ncmFwaGljcy5weQ==) | `81.46% <81.46%> (ø)` | |

[jdebacker]

@rickecon All tests passing, including new ones. According to output from demographics.py pop distribution seems to converge. But I do see some odd stuff regarding immigration rates. A few plots to illustrate:

Fertility rates (look ok)

Mortality rates (look ok)

Immigration rates (too high at older ages)

Population distribution transition (see odd uptick at 100):

Original vs Fixed SS population (odd uptick at 100 more apparent here):

I believe the uptick in the adjusted population distribution are a result of the high immigration rates at older ages. I will review the code that backs out these rates as residuals from the transition in the actual population distribution.

[jdebacker]

With the latest commits, we are looking a lot better. Issue was that the UN data has a bin of 100+, who were being counted as age 100, creating a mass there. The module now drops those over age 99.

Updated plots:

[jdebacker]

Plots looking good:

@rickecon This PR is ready for your review. We'll want to merge this one before #897

[rickecon]

@jdebacker. This is great. Merging.