DemARKs to Examples

[sbenthall]

Moving DemARKs into Examples where appropriate.

I'm still not sure which DemARKs are meant to be moved, vs. which are supposed to stay in DemARK.

This PR currently has `HoweWeSolveIndShockConsumerType, as per this issue
econ-ark/DemARK#81

This are some candidates for other DemARKs to move that I made earlier.
https://github.com/econ-ark/DemARK/blob/master/notebooks/GenIncProcessModel.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/IndShockConsumerType.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/ChangeLiqConstr.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/DCEGM-Upper-Envelope.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK-PerfForesightCRRA.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK-Buffer-Stock-Model.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/PerfForesightConsumerType.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/KinkedRconsumerType.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/GenIncProcessModel.ipynb

Could @llorracc give some clarity into the criteria here?

[sbenthall]

These two appear to be near duplicates. Also, the DemARK here is a submodule pulled in to the ReadTheDocs, which adds another wrinkle of complexity to the transfer.
https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/Gentle-Intro-To-HARK-PerfForesightCRRA.ipynb

These three notebooks are definitely documentation and linked, as they are each documentation for a model within ConsIndShockModel
https://github.com/econ-ark/DemARK/blob/master/notebooks/PerfForesightConsumerType.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/IndShockConsumerType.ipynb
https://github.com/econ-ark/DemARK/blob/master/notebooks/KinkedRconsumerType.ipynb

The last of these is currently included as a submodule, along with the Gentle Introduction.

For the purpose of this PR, until I hear otherwise, I'll assume that the scope of this work is to:

• move all these notebooks into the HARK/examples directory
• figure out how to get Sphinx pointed at them from the HARK directory, which would remove the need for the submodules in the Documentation/ directory.

[sbenthall]

The differences between the two Gentle Introduction notebooks is:

• One uses Aleph for surival probability, the other uses 1 - D.
• The Gentle-Intro-To-HARK.ipynb has a second model, adding Income shocks.

This extended one is the one pulled into RTD. So I think the Gentle-Intro-To-HARK-PerfForesightCRRA.ipynb must be an artifact that can be deleted.

[sbenthall]

What remains for this PR is getting Sphinx to read in the notebooks from the examples/ directory instead of from Documentation/submodules/.

I haven't figured out how to do this yet--it's tricky.

But I think it will be easier to do after PR's #469 (changing the RTD index) and #455 (refactoring ConsumptionSaving) have been merged.

[sbenthall]

Rule of Thumb: If the name of a notebook is a name of a type, then that notebook is just documentation of that type, and can go into the examples directory.

[MridulS]

@sbenthall to add the examples (from DemARK) to sidebar https://github.com/econ-ark/HARK/blame/master/Documentation/index.rst#L31

[sbenthall]

Reviewing the DemARKs in light of this rule of thumb, I'm now slating the following notebooks for moving to examples/

• ConsPortfolioModelDoc.ipynb
• GenIncProcessModel.ipynb
• TractableBufferStockQuickDemo.ipynb

[llorracc]

Great, thanks. I think you should remove the "Doc" from their names if they are being explicitly moved into an area that is already designated for documentation. I think "TractableBufferStockQuickDemo" should probably not go; it's really a tool to explore the economic substance of a model, not to document how HARK works. There should be a TractableBufferStock documentation notebook but that doesn't exist yet. While we're at it, though, let's change the name of "TractableBufferStockQuickDemo" to "TractableBufferStock-Interactive" or something like that. (Open it and you'll see why). Others that should definitely go are: IndShockConsumerType KinkedRconsumerType PerForesightConsumerType Others that perhaps should go: LifeCycleModelExample though if it does go into the "examples" area it should lose the "Example" from its filename.

…

On Tue, Feb 4, 2020 at 5:12 PM Sebastian Benthall ***@***.***> wrote: Reviewing the DemARKs in light of this rule of thumb, I'm now slating the following notebooks for moving to examples/ - ConsPortfolioModelDoc.ipynb - GenIncProcessModel.ipynb - TractableBufferStockQuickDemo.ipynb — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#472?email_source=notifications&email_token=AAKCK74FHCDKA55YIWJ35WTRBGHXNA5CNFSM4KH4F6W2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEKYGOTY#issuecomment-581986127>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKCK7YN7E6SSQJ73RA5TCDRBGHXNANCNFSM4KH4F6WQ> .

-- - Chris Carroll

[sbenthall]

Here is the current build of the documentation on this branch:
https://hark-sb.readthedocs.io/en/i459/

There's one trick about the documentation build.
I couldn't figure out how to get Sphinx to look outside of the Documentation/ directory for notebooks.
So in this PR, there is a directory Documentation/example_notebooks/ that contains symbolic links to the notebooks in the examples directory.

As you can see on my RTD build, Sphinx is able to follow these links, which are maintained in the git checkout.

[sbenthall]

econ-ark/DemARK#86 for the TractableBufferstock rename issue. That can't be resolved in this PR because it's a DemARK issue.

[sbenthall]

Made issue for the points about the notebook names here #488
I think it's better to address this in a systematic way rather than whack-a-moling.

[sbenthall]

This is ready for review. Requesting one from @MridulS

[MridulS]

all links on readthedocs look happy!