Add a new intro tutorial (#2991)

* Add a new language introduction tutorial derived from the Bayesian regression tutorials

* Address coments

* Address comments 2

* Address more comments, add intro and conclusion

* Fix some conclusion text and links

* smoke test

* Address comments, add table of contents

* Fix seaborn warnings

* tweak text and fix ylim

* nits

* rename

* remove all references to old intro tutorials

* update index

* Add notes about deprecation to old intros

* fix code links

* Fix more sphinx errors

* fix yet another sphinx error...

* add a couple sentences about elbo estimators

* fix weird commit??

* Speed up inference

* Remove obsolete comment

* regenerate plots

* address comments

Co-authored-by: Fritz Obermeyer <fritz.obermeyer@gmail.com>

docs/source/getting_started.rst

@@ -4,8 +4,7 @@ Getting Started
  - `Install Pyro <http://pyro.ai#install>`_.
 
  - Learn the basic concepts of Pyro:
-   `models <http://pyro.ai/examples/intro_part_i.html>`_ and
-   `inference <http://pyro.ai/examples/svi_part_i.html>`_.
+   `models and inference <http://pyro.ai/examples/intro_long.html>`_
 
  - Dive in to other `tutorials <http://pyro.ai/examples>`_ and
    `examples <https://github.com/pyro-ppl/pyro/tree/dev/examples>`_.

docs/source/inference.rst

@@ -8,7 +8,7 @@ usually involves some sort of optimization. Pyro supports multiple inference alg
 with support for stochastic variational inference (SVI) being the most extensive. 
 Look here for more inference algorithms in future versions of Pyro.
 
-See `Intro II <http://pyro.ai/examples/intro_part_ii.html>`_ for a discussion of inference in Pyro.
+See the `Introductory tutorial <http://pyro.ai/examples/intro_long.html>`_ for a discussion of inference in Pyro.
 
 .. toctree::
    :glob:

pyro/params/param_store.py

@@ -16,7 +16,7 @@ class ParamStoreDict:
     The typical user interacts with the ParamStore primarily through the
     primitive `pyro.param`.
 
-    See `Intro Part II <http://pyro.ai/examples/intro_part_ii.html>`_ for further discussion
+    See `Introduction <http://pyro.ai/examples/intro_long.html>`_ for further discussion
     and `SVI Part I <http://pyro.ai/examples/svi_part_i.html>`_ for some examples.
 
     Some things to bear in mind when using parameters in Pyro:

pyro/primitives.py

@@ -106,8 +106,7 @@ def sample(name, fn, *args, **kwargs):
     """
     Calls the stochastic function ``fn`` with additional side-effects depending
     on ``name`` and the enclosing context (e.g. an inference algorithm).  See
-    `Intro I <http://pyro.ai/examples/intro_part_i.html>`_ and `Intro II
-    <http://pyro.ai/examples/intro_part_ii.html>`_ for a discussion.
+    `Introduction to Pyro <http://pyro.ai/examples/intro_long.html>`_ for a discussion.
 
     :param name: name of sample
     :param fn: distribution class or function

tutorial/source/effect_handlers.ipynb

@@ -34,7 +34,7 @@
     "\n",
     "Inference in probabilistic programming involves manipulating or transforming probabilistic programs written as generative models. For example, nearly all approximate inference algorithms require computing the unnormalized joint probability of values of latent and observed variables under a generative model.\n",
     "\n",
-    "Consider the following example model from the [introductory inference tutorial](http://pyro.ai/examples/intro_part_ii.html):"
+    "Consider the following example model:"
    ]
   },
   {

tutorial/source/epi_intro.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Epidemiological models: Introduction\n",
     "\n",
-    "This tutorial introduces the [pyro.contrib.epidemiology](http://docs.pyro.ai/en/latest/contrib.epidemiology.html) module, an epidemiological modeling language with a number of black box inference algorithms. This tutorial assumes the reader is already familiar with [modeling](http://pyro.ai/examples/intro_part_ii.html), [inference](http://pyro.ai/examples/intro_part_ii.html), and [distribution shapes](http://pyro.ai/examples/tensor_shapes.html).\n",
+    "This tutorial introduces the [pyro.contrib.epidemiology](http://docs.pyro.ai/en/latest/contrib.epidemiology.html) module, an epidemiological modeling language with a number of black box inference algorithms. This tutorial assumes the reader is already familiar with [modeling](http://pyro.ai/examples/intro_long.html), [inference](http://pyro.ai/examples/intro_long.html), and [distribution shapes](http://pyro.ai/examples/tensor_shapes.html).\n",
     "\n",
     "See also the following scripts:\n",
     "\n",

tutorial/source/index.rst

@@ -13,7 +13,7 @@ please don't hesitate to ask a question on our `forum <https://forum.pyro.ai/>`_
 New users: getting from zero to one
 ------------------------------------
 If you're new to probabilistic programming or variational inference,
-you might want to start by reading the series :ref:`introductory-tutorials`.
+you might want to start by reading the series :ref:`introductory-tutorials`, especially the :doc:`Introduction to Pyro <intro_long>`.
 If you're new to PyTorch, you may also benefit from reading the official introduction `"Deep Learning with PyTorch." <https://pytorch.org/tutorials/beginner/deep_learning_60min_blitz.html>`_
 
 After that, you're ready to get started using Pyro! (Yes, really!)
@@ -76,8 +76,7 @@ List of Tutorials
    :caption: Introductory Tutorials
    :name: introductory-tutorials
 
-   intro_part_i
-   intro_part_ii
+   intro_long
    model_rendering
    svi_part_i
    svi_part_ii
@@ -223,6 +222,14 @@ List of Tutorials
    contrib_funsor_intro_ii
    hmm_funsor
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Deprecated
+   :name: deprecated
+
+   intro_part_i
+   intro_part_ii
+
 Indices and tables
 ==================
 

tutorial/source/intro_part_i.ipynb

@@ -4,7 +4,10 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# An Introduction to Models in Pyro\n",
+    "# (DEPRECATED) An Introduction to Models in Pyro\n",
+    "\n",
+    "## WARNING\n",
+    "***This tutorial has been deprecated*** in favor of the updated [Introduction to Pyro](https://pyro.ai/examples/intro_long.html). It may be removed in the future.***\n",
     "\n",
     "The basic unit of probabilistic programs is the _stochastic function_. \n",
     "This is an arbitrary Python callable that combines two ingredients:\n",
@@ -314,7 +317,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.0"
+   "version": "3.7.6"
   }
  },
  "nbformat": 4,

tutorial/source/logistic-growth.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Logistic growth models of SARS-CoV-2 lineage proportions\n",
     "\n",
-    "This notebook explores logistic growth models, with the goal of inferring the differential growth rates of different SARS-CoV-2 lineages over time. Before this tutorial you may want to familiarize yourself with [Pyro modeling basics](http://pyro.ai/examples/intro_part_i.html) and [tensor shapes](http://pyro.ai/examples/tensor_shapes.html) in Pyro and PyTorch.\n",
+    "This notebook explores logistic growth models, with the goal of inferring the differential growth rates of different SARS-CoV-2 lineages over time. Before this tutorial you may want to familiarize yourself with [Pyro modeling basics](http://pyro.ai/examples/intro_long.html) and [tensor shapes](http://pyro.ai/examples/tensor_shapes.html) in Pyro and PyTorch.\n",
     "\n",
     "**WARNING**: The purpose of this tutorial is to demonstrate Pyro's modeling and inference syntax. \n",
     "Making reliable inferences about SARS-CoV-2 **is not** the purpose of this tutorial.\n",

tutorial/source/modules.ipynb

@@ -7,7 +7,7 @@
     "# Modules in Pyro\n",
     "\n",
     "\n",
-    "This tutorial introduces [PyroModule](http://docs.pyro.ai/en/stable/nn.html#pyro.nn.module.PyroModule), Pyro's Bayesian extension of PyTorch's [nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) class. Before starting you should understand the basics of Pyro [models](http://pyro.ai/examples/intro_part_i.html) and [inference](http://pyro.ai/examples/intro_part_ii.html), understand the two primitives [pyro.sample()](http://docs.pyro.ai/en/stable/primitives.html#pyro.primitives.sample) and [pyro.param()](http://docs.pyro.ai/en/stable/primitives.html#pyro.primitives.param), and understand the basics of Pyro's [effect handlers](http://pyro.ai/examples/effect_handlers.html) (e.g. by browsing [minipyro.py](https://github.com/pyro-ppl/pyro/blob/dev/pyro/contrib/minipyro.py)).\n",
+    "This tutorial introduces [PyroModule](http://docs.pyro.ai/en/stable/nn.html#pyro.nn.module.PyroModule), Pyro's Bayesian extension of PyTorch's [nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) class. Before starting you should understand the basics of Pyro [models and inference](http://pyro.ai/examples/intro_long.html), understand the two primitives [pyro.sample()](http://docs.pyro.ai/en/stable/primitives.html#pyro.primitives.sample) and [pyro.param()](http://docs.pyro.ai/en/stable/primitives.html#pyro.primitives.param), and understand the basics of Pyro's [effect handlers](http://pyro.ai/examples/effect_handlers.html) (e.g. by browsing [minipyro.py](https://github.com/pyro-ppl/pyro/blob/dev/pyro/contrib/minipyro.py)).\n",
     "\n",
     "#### Summary:\n",
     "\n",

tutorial/source/svi_part_i.ipynb

@@ -10,7 +10,7 @@
     "\n",
     "## Setup\n",
     "\n",
-    "We're going to assume we've already defined our model in Pyro (for more details on how this is done see [Intro Part I](intro_part_i.ipynb)).\n",
+    "We're going to assume we've already defined our model in Pyro (for more details on how this is done see [Introduction to Pyro](intro_long.ipynb)).\n",
     "As a quick reminder, the model is given as a stochastic function `model(*args, **kwargs)`, which, in the general case takes arguments. The different pieces of `model()` are encoded via the mapping:\n",
     "\n",
     "1. observations $\\Longleftrightarrow$ `pyro.sample` with the `obs` argument\n",