Update model averaging to book style (pymc-devs#414)

* notebook: model_averaging (header,footer updates) * model_averaging: adding myst file * add watermark header; add footer * rerunning myst file * update notebook tags * recreate myst file after updating notebook tags * minor text fixes * adding myst file * add References section at the end * add myst file * add 2 more urls to list in pre-commit yaml file * update yaml, bibtext, citation references * adding myst file * remove end of | * revert unwanted updates to moderation_analysis + add excluded nb link
Sriatunckfbs · Sep 21, 2022 · 9fad19c · 9fad19c
1 parent aa1ee22
commit 9fad19c
Show file tree

Hide file tree

Showing 4 changed files with 328 additions and 143 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -82,7 +82,8 @@ repos:
                examples/samplers/SMC-ABC_Lotka-Volterra_example.ipynb|
                examples/splines/spline.ipynb|
                examples/survival_analysis/censored_data.ipynb|
-               examples/survival_analysis/weibull_aft.ipynb)
+               examples/survival_analysis/weibull_aft.ipynb|
+               examples/howto/custom_distribution.ipynb)
       entry: >
           (?x)(arviz-devs.github.io|
                aesara.readthedocs.io|
@@ -94,7 +95,9 @@ repos:
                docs.python.org|
                xarray.pydata.org
                python.arviz.org|
-               docs.xarray.dev)
+               docs.xarray.dev|
+               www.pymc.io|
+               docs.scipy.org/doc)
       language: pygrep
       types_or: [markdown, rst, jupyter]
 - repo: https://github.com/mwouts/jupytext

diff --git a/examples/diagnostics_and_criticism/model_averaging.ipynb b/examples/diagnostics_and_criticism/model_averaging.ipynb
diff --git a/examples/references.bib b/examples/references.bib
@@ -481,6 +481,18 @@ @book{wilkinson2005grammar
   issn          = {1431-8784},
   isbn          = {978-0-387-24544-7}
 }
+@article{Yao_2018,
+  doi           = {10.1214/17-ba1091},
+  url           = {https://doi.org/10.1214\%2F17-ba1091},
+  year          = 2018,
+  month         = {sep},
+  publisher     = {Institute of Mathematical Statistics},
+  volume        = {13},
+  number        = {3},
+  author        = {Yuling Yao and Aki Vehtari and Daniel Simpson and Andrew Gelman},
+  title         = {Using Stacking to Average Bayesian Predictive Distributions (with Discussion)},
+  journal       = {Bayesian Analysis}
+}
 @article{yuan2009bayesian,
   title         = {Bayesian mediation analysis.},
   author        = {Yuan, Ying and MacKinnon, David P},

diff --git a/myst_nbs/diagnostics_and_criticism/model_averaging.myst.md b/myst_nbs/diagnostics_and_criticism/model_averaging.myst.md
@@ -6,11 +6,20 @@ jupytext:
     format_version: 0.13
     jupytext_version: 1.13.7
 kernelspec:
-  display_name: Python PyMC3 (Dev)
+  display_name: Python 3 (ipykernel)
   language: python
-  name: pymc3-dev-py38
+  name: python3
 ---
 
+(model_averaging)=
+# Model Averaging
+
+:::{post} Aug 2022
+:tags: model comparison, model averaging
+:category: intermediate
+:author: Osvaldo Martin
+:::
+
 ```{code-cell} ipython3
 ---
 papermill:
@@ -27,7 +36,7 @@ import numpy as np
 import pandas as pd
 import pymc3 as pm
 
-print(f"Running on PyMC3 v{pm.__version__}")
+print(f"Running on PyMC3 v{pm.__version__}")
 ```
 
 ```{code-cell} ipython3
@@ -47,17 +56,16 @@ az.style.use("arviz-darkgrid")
 
 +++ {"papermill": {"duration": 0.068882, "end_time": "2020-11-29T12:13:08.020372", "exception": false, "start_time": "2020-11-29T12:13:07.951490", "status": "completed"}, "tags": []}
 
-# Model averaging
-
-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_comparison.ipynb) and this other [example](GLM-model-selection.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 just keep a point-estimate like the posterior mean; we may become overconfident of what we really know.
+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 the PyMC examples {ref}`pymc:model_comparison` and the {ref}`GLM-model-selection`. 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 just keep a point-estimate like the posterior mean; we may become overconfident of what we really know. You can also browse the {doc}`blog/tag/model-comparison` tag to find related posts. 
 
 One alternative is to perform model selection but discuss 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.
 
-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. There are several ways to do this and PyMC3 includes 3 of them that we are going to briefly discuss, you will find a more thorough explanation in the work by [Yuling Yao et. al.](https://arxiv.org/abs/1704.02030)
+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. There are several ways to do this and PyMC includes 3 of them that we are going to briefly discuss, you will find a more thorough explanation in the work by {cite:t}`Yao_2018`. PyMC integrates with ArviZ for model comparison. 
+
 
 ## Pseudo Bayesian model averaging
 
-Bayesian models can be weighted by their marginal likelihood, this is known as Bayesian Model Averaging. While this is theoretically appealing, is problematic in practice: on the one hand the marginal likelihood is highly sensible to the specification of the prior, in a way that parameter estimation is not, and on the other computing the marginal likelihood is usually a challenging task. An alternative route is to use the values of WAIC (Widely Applicable Information Criterion) or LOO (pareto-smoothed importance sampling Leave-One-Out cross-validation), which we will call generically IC, to estimate weights. We can do this by using the following formula:
+Bayesian models can be weighted by their marginal likelihood, this is known as Bayesian Model Averaging. While this is theoretically appealing, it is problematic in practice: on the one hand the marginal likelihood is highly sensible to the specification of the prior, in a way that parameter estimation is not, and on the other, computing the marginal likelihood is usually a challenging task. An alternative route is to use the values of WAIC (Widely Applicable Information Criterion) or LOO (pareto-smoothed importance sampling Leave-One-Out cross-validation), which we will call generically IC, to estimate weights. We can do this by using the following formula:
 
 $$w_i = \frac {e^{ - \frac{1}{2} dIC_i }} {\sum_j^M e^{ - \frac{1}{2} dIC_j }}$$
 
@@ -71,7 +79,7 @@ The above formula for computing weights is a very nice and simple approach, but
 
 ## Stacking
 
-The third approach implemented in PyMC3 is know as _stacking of predictive distributions_ and it has been recently [proposed](https://arxiv.org/abs/1704.02030). We want to combine several models in a metamodel in order to minimize the diverge between the meta-model and the _true_ generating model, when using a logarithmic scoring rule this is equivalently to:
+The third approach implemented in PyMC is known as _stacking of predictive distributions_ by {cite:t}`Yao_2018`. We want to combine several models in a metamodel in order to minimize the divergence between the meta-model and the _true_ generating model, when using a logarithmic scoring rule this is equivalent to:
 
 $$\max_{w} \frac{1}{n} \sum_{i=1}^{n}log\sum_{k=1}^{K} w_k p(y_i|y_{-i}, M_k)$$
 
@@ -81,11 +89,11 @@ The quantity $p(y_i|y_{-i}, M_k)$ is the leave-one-out predictive distribution f
 
 ## Weighted posterior predictive samples
 
-Once we have computed the weights, using any of the above 3 methods,  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.
+Once we have computed the weights, using any of the above 3 methods,  we can use them to get a weighted posterior predictive samples. PyMC offers functions to perform these steps in a simple way, so let see them in action using an example.
 
-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.
+The following example is taken from the superb book {cite:t}`mcelreath2018statistical` by Richard McElreath. You will find more PyMC examples from this book in the repository [Statistical-Rethinking-with-Python-and-PyMC](https://github.com/pymc-devs/pymc-resources/tree/main/Rethinking_2). 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.
 
-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:
+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 an 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:
 
 1. A model using only the neocortex variable
 2. A model using only the logarithm of the mass variable
@@ -211,7 +219,7 @@ az.plot_forest(traces, figsize=(10, 5));
 
 +++ {"papermill": {"duration": 0.052958, "end_time": "2020-11-29T12:14:55.196722", "exception": false, "start_time": "2020-11-29T12:14:55.143764", "status": "completed"}, "tags": []}
 
-Another option is to plot several traces in a same plot is to use `densityplot`. This plot is somehow similar to a forestplot, but we get truncated KDE plots (by default 95% credible intervals) grouped by variable names together with a point estimate (by default the mean).
+Another option is to plot several traces in a same plot is to use `plot_density`. This plot is somehow similar to a forestplot, but we get truncated KDE (kernel density estimation) plots (by default 95% credible intervals) grouped by variable names together with a point estimate (by default the mean).
 
 ```{code-cell} ipython3
 ---
@@ -223,12 +231,25 @@ papermill:
   status: completed
 tags: []
 ---
-az.plot_density(traces, var_names=["alpha", "sigma"]);
+ax = az.plot_density(
+    traces,
+    var_names=["alpha", "sigma"],
+    shade=0.1,
+    data_labels=["Model 0 (neocortex)", "Model 1 (log_mass)", "Model 2 (neocortex+log_mass)"],
+)
+
+ax[0, 0].set_xlabel("Density")
+ax[0, 0].set_ylabel("")
+ax[0, 0].set_title("95% Credible Intervals: alpha")
+
+ax[0, 1].set_xlabel("Density")
+ax[0, 1].set_ylabel("")
+ax[0, 1].set_title("95% Credible Intervals: sigma")
 ```
 
 +++ {"papermill": {"duration": 0.055089, "end_time": "2020-11-29T12:14:57.977616", "exception": false, "start_time": "2020-11-29T12:14:57.922527", "status": "completed"}, "tags": []}
 
-Now that we have sampled the posterior for the 3 models, we are going to use WAIC (Widely applicable information criterion) to compare the 3 models. We can do this using the `compare` function included with PyMC3.
+Now that we have sampled the posterior for the 3 models, we are going to use WAIC (Widely applicable information criterion) to compare the 3 models. We can do this using the `compare` function included with ArviZ.
 
 ```{code-cell} ipython3
 ---
@@ -247,11 +268,11 @@ comp
 
 +++ {"papermill": {"duration": 0.056609, "end_time": "2020-11-29T12:14:58.387481", "exception": false, "start_time": "2020-11-29T12:14:58.330872", "status": "completed"}, "tags": []}
 
-We can see that the best model is `model_2`, the one with both predictor variables. Notice the DataFrame is ordered from lowest to highest WAIC (_i.e_ from _better_ to _worst_ model). Check [this notebook](model_comparison.ipynb) for a more detailed discussing on model comparison.
+We can see that the best model is `model_2`, the one with both predictor variables. Notice the DataFrame is ordered from lowest to highest WAIC (_i.e_ from _better_ to _worst_ model). Check the {ref}`pymc:model_comparison` for a more detailed discussion on model comparison.
 
-We can also see that we get a column with the relative `weight` for each model (according to the first equation at the beginning of this notebook). This weights can be _vaguely_ interpreted as the probability that each model will make the correct predictions on future data. Of course this interpretation is conditional on the models used to compute the weights, if we add or remove models the weights will change. And also is dependent on the assumptions behind WAIC (or any other Information Criterion used). So try to do not overinterpret these `weights`. 
+We can also see that we get a column with the relative `weight` for each model (according to the first equation at the beginning of this notebook). This weights can be _vaguely_ interpreted as the probability that each model will make the correct predictions on future data. Of course this interpretation is conditional on the models used to compute the weights, if we add or remove models the weights will change. And also is dependent on the assumptions behind WAIC (or any other Information Criterion used). So try to not overinterpret these `weights`. 
 
-Now we are going to use copmuted `weights` to generate predictions based not on a single model but on the weighted set of models. This is one way to perform model averaging. Using PyMC3 we can call the `sample_posterior_predictive_w` function as follows:
+Now we are going to use computed `weights` to generate predictions based not on a single model, but on the weighted set of models. This is one way to perform model averaging. Using PyMC we can call the `sample_posterior_predictive_w` function as follows:
 
 ```{code-cell} ipython3
 ---
@@ -275,7 +296,7 @@ ppc_w = pm.sample_posterior_predictive_w(
 
 Notice that we are passing the weights ordered by their index. We are doing this because we pass `traces` and `models` ordered from model 0 to 2, but the computed weights are ordered from lowest to highest WAIC (or equivalently from larger to lowest weight). In summary, we must be sure that we are correctly pairing the weights and models.
 
-We are also going to compute PPCs for the lowest-WAIC model
+We are also going to compute PPCs for the lowest-WAIC model.
 
 ```{code-cell} ipython3
 ---
@@ -292,7 +313,7 @@ ppc_2 = pm.sample_posterior_predictive(trace=trace_2, model=model_2, progressbar
 
 +++ {"papermill": {"duration": 0.058214, "end_time": "2020-11-29T12:15:55.404271", "exception": false, "start_time": "2020-11-29T12:15:55.346057", "status": "completed"}, "tags": []}
 
-A simple way to compare both kind of predictions is to plot their mean and hpd interval
+A simple way to compare both kind of predictions is to plot their mean and hpd interval.
 
 ```{code-cell} ipython3
 ---
@@ -329,7 +350,30 @@ As we can see the mean value is almost the same for both predictions but the unc
 
 There are other ways to average models such as, for example, explicitly building a meta-model that includes all the models we have. We then perform parameter inference while jumping between the models. One problem with this approach is that jumping between models could hamper the proper sampling of the posterior.
 
-Besides averaging discrete models we can sometimes think of continuous versions of them. A toy example is to imagine that we have a coin and we want to estimated it's degree of bias, a number between 0 and 1 being 0.5 equal chance of head and tails. We could think of two separated models one with a prior biased towards heads and one towards tails. We could fit both separate models and then average them using, for example, IC-derived weights. An alternative, is to build a hierarchical model to estimate the prior distribution, instead of contemplating two discrete models we will be computing a continuous model that includes these the discrete ones as particular cases. Which approach is better? That depends on our concrete problem. Do we have good reasons to think about two discrete models, or is our problem better represented with a continuous bigger model?
+Besides averaging discrete models we can sometimes think of continuous versions of them. A toy example is to imagine that we have a coin and we want to estimated its degree of bias, a number between 0 and 1 having a 0.5 equal chance of head and tails (fair coin). We could think of two separate models one with a prior biased towards heads and one towards tails. We could fit both separate models and then average them using, for example, IC-derived weights. An alternative, is to build a hierarchical model to estimate the prior distribution, instead of contemplating two discrete models we will be computing a continuous model that includes these the discrete ones as particular cases. Which approach is better? That depends on our concrete problem. Do we have good reasons to think about two discrete models, or is our problem better represented with a continuous bigger model?
+
++++
+
+## Authors
+
+* Authored by Osvaldo Martin in June 2017 ([pymc#2273](https://github.com/pymc-devs/pymc/pull/2273))
+* Updated by Osvaldo Martin in December 2017 ([pymc#2741](https://github.com/pymc-devs/pymc/pull/2741))
+* Updated by Marco Gorelli in November 2020 ([pymc#4271](https://github.com/pymc-devs/pymc/pull/4271))
+* Moved from pymc to pymc-examples repo in December 2020 ([pymc-examples#8](https://github.com/pymc-devs/pymc-examples/pull/8))
+* Updated by Raul Maldonado in February 2021 ([pymc#25](https://github.com/pymc-devs/pymc-examples/pull/25))
+* Updated Markdown and styling by @reshamas in August 2022, ([pymc-examples#414](https://github.com/pymc-devs/pymc-examples/pull/414))
+
++++
+
+## References
+
+:::{bibliography}
+:filter: docname in docnames
+:::
+
++++
+
+## Watermark
 
 ```{code-cell} ipython3
 ---
@@ -344,3 +388,6 @@ tags: []
 %load_ext watermark
 %watermark -n -u -v -iv -w
 ```
+
+:::{include} ../page_footer.md
+:::