diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 3dfa13cc29..f5614180ee 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -12,6 +12,8 @@ Howto
notebooks/sampler-stats.ipynb
notebooks/Diagnosing_biased_Inference_with_Divergences.ipynb
notebooks/posterior_predictive.ipynb
+ notebooks/model_comparison.ipynb
+ notebooks/model_averaging.ipynb
notebooks/howto_debugging.ipynb
notebooks/PyMC3_tips_and_heuristic.ipynb
notebooks/LKJ.ipynb
diff --git a/docs/source/notebooks/model_averaging.ipynb b/docs/source/notebooks/model_averaging.ipynb
new file mode 100644
index 0000000000..ff43209701
--- /dev/null
+++ b/docs/source/notebooks/model_averaging.ipynb
@@ -0,0 +1,495 @@
+{
+ "cells": [
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "%matplotlib inline\n",
+ "import matplotlib.pyplot as plt\n",
+ "plt.style.use(['seaborn-darkgrid', 'seaborn-colorblind'])\n",
+ "import pymc3 as pm\n",
+ "import numpy as np\n",
+ "import pandas as pd\n",
+ "from theano import shared"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "When confronted with more than one model we have several options. One of them is to perform model selection, using for example a given Information Criterion as exemplified [in this notebook](model_comparsion.ipynb) and this other [example](model_comparsion.ipynb). Model selection is appealing for its simplicity, but we are discarding information about the uncertainty in our models. This is somehow similar to computing the full posterior and then keep just keep a point-estimate like the posterior mean; we may become overconfident of what we really know.\n",
+ "\n",
+ "One alternative is to perform model selection but discuss the all the different models together with the computed values of a given Information Criterion. It is important to put all these numbers and tests in the context of our problem so that we and our audience can have a better feeling of the possible limitations and shortcomings of our methods. If you are in the academic world you can use this approach to add elements to the discussion section of a paper, presentation, thesis, and so on.\n",
+ "\n",
+ "Yet another approach is to perform model averaging. The idea now is to generate a meta-model (and meta-predictions) using a weighted average of the models. One way to compute these weights is to apply this formula:\n",
+ "\n",
+ "$$w_i = \\frac {e^{ \\frac{1}{2} dIC_i }} {\\sum_j^M e^{ - \\frac{1}{2} dIC_j }}$$\n",
+ "\n",
+ "Where $dIC_i$ is the difference between the i-esim information criterion value and the lowest one. Remember that the lowest the value of the IC, the better. We can use any information criterion we want to compute a set of weights, but, of course, we cannot mix them. \n",
+ "\n",
+ "This formula is a heuristic way to compute the relative probability of each model (given a fixed set of models) from the information criteria values. Look how the denominator is just a normalization term to ensure that the weights sum up to one.\n",
+ "\n",
+ "Once we have computed the weights we can use them to get a weighted posterior predictive samples. PyMC3 offers functions to perform these steps in a simple way, so let see them in action using an example.\n",
+ "\n",
+ "The following example is taken from the superb book [Statistical Rethinking](http://xcelab.net/rm/statistical-rethinking/) by Richard McElreath. You will find more PyMC3 examples from this book in this [repository](https://github.com/aloctavodia/Statistical-Rethinking-with-Python-and-PyMC3). We are going to explore a simplified version of it. Check the book for the whole example and a more thorough discussion of both, the biological motivation for this problem and a theoretical/practical discussion of using Information Criteria to compare, select and average models.\n",
+ "\n",
+ "Briefly, our problem is as follows: We want to explore the composition of milk across several primate species, it is hypothesized that females from species of primates with larger brains produce more _nutritious_ milk (loosely speaking this is done _in order to_ support the development of such big brains). This is an important question for evolutionary biologists and try to give and answer we will use 3 variables, two predictor variables: the proportion of neocortex compare to the total mass of the brain and the logarithm of the body mass of the mothers. And for predicted variable, the kilocalories per gram of milk. With these variables we are going to build 3 different linear models:\n",
+ " \n",
+ "1. A model using only the neocortex variable\n",
+ "2. A model using only the logarithm of the mass variable\n",
+ "3. A model using both variables\n",
+ "\n",
+ "Let start by uploading the data and centering the `neocortex` and `log mass` variables, for better sampling."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " kcal.per.g | \n",
+ " neocortex | \n",
+ " log_mass | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " 0.49 | \n",
+ " -0.123706 | \n",
+ " -0.831353 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " 0.47 | \n",
+ " -0.030706 | \n",
+ " 0.158647 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " 0.56 | \n",
+ " -0.030706 | \n",
+ " 0.181647 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " 0.89 | \n",
+ " 0.000294 | \n",
+ " -0.579353 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " 0.92 | \n",
+ " 0.012294 | \n",
+ " -1.885353 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " WAIC | \n",
+ " pWAIC | \n",
+ " dWAIC | \n",
+ " weight | \n",
+ " SE | \n",
+ " dSE | \n",
+ " warning | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 2 | \n",
+ " -15.5565 | \n",
+ " 2.44088 | \n",
+ " 0 | \n",
+ " 0.951596 | \n",
+ " 4.7749 | \n",
+ " 0 | \n",
+ " 1 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " -8.99463 | \n",
+ " 2.01189 | \n",
+ " 6.56192 | \n",
+ " 0.0357726 | \n",
+ " 4.1411 | \n",
+ " 0.889976 | \n",
+ " 1 | \n",
+ "
\n",
+ " \n",
+ " | 0 | \n",
+ " -6.91266 | \n",
+ " 1.9867 | \n",
+ " 8.64388 | \n",
+ " 0.0126316 | \n",
+ " 3.1031 | \n",
+ " 3.81202 | \n",
+ " 0 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "