econ-ark · willingc · Jul 22, 2019 · Jul 22, 2019 · Jul 22, 2019 · Jul 22, 2019
diff --git a/README.md b/README.md
@@ -2,27 +2,65 @@
 
 This repository contains demos and documentation for [HARK](https://github.com/econ-ark/HARK).
 
-[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/econ-ark/DemARK/master)
+## Try the notebooks on Binder
 
-## Local installation
-
-### Option 1: With Jupyter
-
-0. [Install jupyter](https://jupyter.org/install).
-1. Clone `DemARK` to the folder of your choice
-2. Run `pip install -r binder/requirements.txt` to install dependencies
-3. Enable notebook extensions.
+**No installation is needed. Runs in a web browser**
 
-   **On Linux/macOS:**
+Click the Binder link. Binder builds an environment in the cloud for you to use.
+The first time Binder launches it may take a while since it is busy creating a
+container to run the demo notebooks. Subsequent launches should be quicker.
 
-   Run `binder/postBuild` in your terminal (at a shell in the binder directory, `./postBuild`)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/econ-ark/DemARK/master)
 
-   **On Windows:**
 
-   Run `binder/postBuild.bat`
+## Local installation
 
-4. Run `jupyter notebook` from the `DemARK` root folder. You will be prompted to open a page in your web browser. From there, you will be able to run the notebooks.
-5. Run the notebook by clicking the `▶▶` button or choosing `Kernel → Restart & Run All`
+The installation instructions are provided for Python 3.6+.
+
+### Option 1a: With Jupyter using pip
+
+1. Create a virtual environment (using the CPython `venv` command).
+2. Activate the `myarkenv` environment.
+3. Upgrade pip.
+4. Use pip to install requirements.
+5. Add and enable notebook extensions
+6. Run Jupyter notebook.
+
+```
+python3 -m venv myarkenv
+source myarkenv/bin/activate
+pip install --upgrade pip
+pip install -r requirements.txt
+jupyter contrib nbextension install --user  # installs css/js and nbconvert config info
+jupyter nbextension enable codefolding/main  # enable codefolding in a notebook code cell
+jupyter nbextension enable codefolding/edit  # enable codefolding in editor
+jupyter nbextension enable --py latex_envs  # enable some latex features into notebook
+python3 -m cite2c.install  # Enables the cite2c extension (you will need to log into zotero if you use this extension) **Optional**
+jupyter notebook
+```
+
+This will launch the jupyter file browser. The notebooks can be selected and
+run.
+
+Locally, you can enable/disable extensions by: http://localhost:8888/nbextensions. More information can be found in the [notebook extensions documentation](https://jupyter-contrib-nbextensions.readthedocs.io)
+
+---
+
+### Option 1b: With Jupyter using conda
+
+Using conda from Anaconda or miniconda, enter the following to create a local
+conda environment.
+
+```
+conda env create -f environment.yml
+conda activate demos
+jupyter contrib nbextension install --user  # installs css/js and nbconvert config info
+jupyter nbextension enable codefolding/main  # enable codefolding in a notebook code cell
+jupyter nbextension enable codefolding/edit  # enable codefolding in editor
+jupyter nbextension enable --py latex_envs  # enable some latex features into notebook
+python3 -m cite2c.install  # Enables the cite2c extension (you will need to log into zotero if you use this extension) **Optional**
+jupyter notebook
+```
 
 ### Option 2: With Docker and repo2docker
 
@@ -32,13 +70,14 @@ This repository contains demos and documentation for [HARK](https://github.com/e
 3. Follow the link in your terminal to the running instance of jupyter
 4. Run the notebook by clicking the `▶▶` button or choosing `Kernel → Restart & Run All`
 
+
 ## Contributions
 
 We are eager to encourage contributions.
 
 These can take the form either of new notebooks, or proposed edits for existing notebooks. Either kind of contribution can be made by issuing a pull request.
 
-However, to deal with the well-known problem that normal jupyter notebooks do not "play nicely" with github version control, we will require interactions 
+However, to deal with the well-known problem that normal jupyter notebooks do not "play nicely" with github version control, we will require interactions
 with contributors to be conducted after the installation of the [jupytext](https://towardsdatascience.com/introducing-jupytext-9234fdff6c57) tool.
 Specifically, you will need to follow the instructions for installing jupytext on your computer, and then need to configure it to use the "percent"
 format. Over time, we intend to add the necessary metadata to all our jupyter notebooks to make them automatically invoke jupytext when compiled.

diff --git a/binder/postBuild b/binder/postBuild
@@ -1,9 +1,16 @@
 #!/bin/sh
+
+# Install and enable notebook extensions
+# https://jupyter-contrib-nbextensions.readthedocs.io
 jupyter contrib nbextension install --user
 jupyter nbextension enable codefolding/main
 jupyter nbextension enable codefolding/edit
-jupyter nbextension enable latex_envs
+jupyter nbextension enable --py latex_envs
+
+# Enable cite2c extension
 python -m cite2c.install
+
+# Add zotero credential to notebook configuration
 result=$(python <<EOF
 from notebook.services.config.manager import ConfigManager
 cm = ConfigManager()

diff --git a/binder/postBuild.bat b/binder/postBuild.bat
diff --git a/binder/requirements.txt b/binder/requirements.txt
@@ -1,9 +1,8 @@
-matplotlib==2.1.2
-numpy==1.14.0
-ipywidgets==7.2.1
-scipy==1.0.0
-jupyter_contrib_nbextensions
 cite2c
 econ-ark==0.10.1.dev3
-
-
+ipywidgets
+jupyter
+jupyter_contrib_nbextensions
+matplotlib
+numpy
+scipy
diff --git a/binder/runtime.txt b/binder/runtime.txt
diff --git a/docs/about_repo.md b/docs/about_repo.md
@@ -0,0 +1,29 @@
+# About DemARK
+
+## Repo Layout
+
+The root of the DemARK repo contains the following:
+
+**Directories**
+
+- `binder` contains configuration for the mybinder.org service
+- `docs` contains docs about the repo
+- `lib` contains utilities such as progress bars
+- `notebooks` contains Jupyter notebooks and Python files for different topics
+
+**Files**
+
+- README.md
+- `environment.yml`: for local conda install
+- `requirements.txt`: for local pip install
+- `tasks.py`: configuration for invoke
+- `talks.yml`: allows a repo to be configured for a particular workshop or talk. See JupyterLab demo repo for more info.
+
+## Binder configuration
+
+- The `binder` directory contains configuration for the mybinder.org service.
+- If a `binder` directory is not present, mybinder.org will default to using the `environment.yml` file when launching.
+- The `binder` configuration includes several files:
+    - `environment.yml` conda and conda-forge config for repo on binder service
+    - `postBuid` commands that are executed by Binder after an initial environment is set up
+
diff --git a/docs/todo.md b/docs/todo.md
@@ -0,0 +1,42 @@
+# To Do list
+
+## Security
+
+- hash or hide zotero credential token
+
+## Enhancements for Binder or Local use
+- Add invoke to simplify for local user setup (similar to jupyterlab demo)
+- Use environment.yml and conda-forge in Binder
+- To Pin or not to pin requirements
+
+## Tests
+
+- Add basic tests for running notebooks success (Papermill or invoke)
+
+## Notebook issues
+
+- Check MyType error in Alternative-Combos-Of-Parameter-Values.ipynb
+
+### Latex Errors
+
+Latex errors Gentle-Intro-To-HARK-Buffer-Stock-Model nb
+
+### Runtime or module errors (version or logic error?)
+- /srv/conda/envs/notebook/lib/python3.7/site-packages/HARK/interpolation.py:1675: RuntimeWarning: All-NaN slice encountered
+- LifecycleModelExample nb error No module named 'HARK.SolvingMicroDSOPs.EstimationParameters'
+
+### Can't find data file
+
+- MicroMacroProblems Both nbs error at Lorenz cell FileNotFoundError: [Errno 2] No such file or directory: '/srv/conda/envs/notebook/lib/python3.7/site-packages/HARK/cstwMPC/USactuarial.txt'
+- StructuralEstimates nb error FileNotFoundError: [Errno 2] No such file or directory: '/srv/conda/envs/notebook/lib/python3.7/site-packages/HARK/cstwMPC/USactuarial.txt'
+- Uncertainty-and-Savings-Rate nb No such file or directory: '/srv/conda/envs/notebook/lib/python3.7/site-packages/HARK/cstwMPC/USactuarial.txt'
+
+
+### Slow, Runs until student exercise
+
+- Check heading click for DCEGM-Upper-Envelope nb
+- Check last cell execution Fashion-Victim-Model nb (It works but serializes execution) Slow
+- KrusellSmith.ipynb Solver is slow...
+- IncExpectation notebooks are slow...
+- Runs until student exercise: Gentle-Intro-To-HARK-PerfForesightCRRA
+- Runs until student exercise: Latex?? Gentle-Intro-To-HARK
diff --git a/environment.yml b/environment.yml
@@ -0,0 +1,15 @@
+name: demos
+channels:
+- conda-forge
+dependencies:
+# Jupyter
+- ipywidgets
+- jupyter
+- jupyter_contrib_nbextensions
+# libraries
+- matplotlib
+- numpy
+- scipy
+- pip:
+  - cite2c
+  - econ-ark==0.10.1.dev
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,8 @@
+cite2c
+econ-ark
+ipywidgets
+jupyter
+jupyter_contrib_nbextensions
+matplotlib
+numpy
+scipy