Add intro tutorial to contrib.epidemiology

docs/source/contrib.epidemiology.rst

@@ -5,16 +5,18 @@ Epidemiology
 .. warning:: Code in ``pyro.contrib.epidemiology`` is under development.
     This code makes no guarantee about maintaining backwards compatibility.
 
-``pyro.contrib.epidemiology`` is a framework for experimenting with a
-restricted class of stochastic discrete-time discrete-count compartmental
-models. This framework implements **inference** (both Stochastic Variational
-Inference and Hamiltonian Monte Carlo), **prediction** of latent variables, and
+``pyro.contrib.epidemiology`` provides a modeling language for a class of
+stochastic discrete-time discrete-count compartmental models. This module
+implements black-box **inference** (both Stochastic Variational Inference and
+Hamiltonian Monte Carlo), **prediction** of latent variables, and
 **forecasting** of future trajectories.
 
-For example usage see the `SIR tuorial <http://pyro.ai/examples/contrib/epidemiology/sir.html>`_ .
+For example usage see the following tutorials:
 
-For explanation of the underlying inference machinery in this framework, see the
-`low-level SIR with HMC tutorial <http://pyro.ai/examples/sir_hmc.html>`_ .
+- `Introduction <http://pyro.ai/examples/epi_intro.html>`_
+- `Univariate models <http://pyro.ai/examples/epi_sir.html>`_
+- `Regional models <http://pyro.ai/examples/epi_regional.html>`_
+- `Inference via auxiliary variable HMC <http://pyro.ai/examples/sir_hmc.html>`_
 
 Base Compartmental Model
 ------------------------

pyro/contrib/epidemiology/compartmental.py

@@ -87,7 +87,7 @@ def transition(self, params, state, t): ...
     good model structure and priors, then move to more accurate but more
     expensive inference once the model is plausible.
 
-    1.  Start with ``.fit_svi(guide_rank=1, num_steps=2000)`` for cheap
+    1.  Start with ``.fit_svi(guide_rank=0, num_steps=2000)`` for cheap
         inference while you search for a good model.
     2.  Additionally infer long-range correlations by moving to a low-rank
         multivariate normal guide via ``.fit_svi(guide_rank=None,

tutorial/source/enumeration.ipynb

@@ -637,7 +637,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.10"
+   "version": "3.7.7"
   }
  },
  "nbformat": 4,

tutorial/source/epi_regional.rst

@@ -0,0 +1,13 @@
+Epidemiological models: Regional
+================================
+
+`View regional.py on github`__
+
+.. _github: https://github.com/pyro-ppl/pyro/blob/dev/examples/contrib/epidemiology/regional.py
+
+__ github_
+
+.. literalinclude:: ../../examples/contrib/epidemiology/regional.py
+    :language: python
+
+

tutorial/source/epi_sir.rst

@@ -0,0 +1,12 @@
+Epidemiological models: Univariate
+==================================
+
+`View sir.py on github`__
+
+.. _github: https://github.com/pyro-ppl/pyro/blob/dev/examples/contrib/epidemiology/sir.py
+
+__ github_
+
+.. literalinclude:: ../../examples/contrib/epidemiology/sir.py
+    :language: python
+

tutorial/source/index.rst

@@ -61,7 +61,8 @@ Welcome to Pyro Examples and Tutorials!
    working_memory
    elections
    dirichlet_process_mixture
-   boosting_bbvi	
+   boosting_bbvi
+   epi_intro
 
 .. toctree::
    :maxdepth: 2
@@ -79,6 +80,8 @@ Welcome to Pyro Examples and Tutorials!
    forecast_simple
    timeseries
    smcfilter
+   epi_sir
+   epi_regional
    sir_hmc
    toy_mixture_model_discrete_enumeration
 

tutorial/source/sir_hmc.rst

@@ -1,5 +1,5 @@
-Compartmental Epidemiological Models
-====================================
+Epidemiological inference via HMC
+=================================
 
 This tutorial is in the form of a script (see below).