Merge pull request #215 from pymc-labs/references

Enable bibtex references in the documentation

Author: drbenvincent

.pre-commit-config.yaml

@@ -36,7 +36,7 @@ repos:
     - repo: https://github.com/econchick/interrogate
       rev: 1.5.0
       hooks:
-          - id: interrogate
-            # needed to make excludes in pyproject.toml work
-            # see here https://github.com/econchick/interrogate/issues/60#issuecomment-735436566
-            pass_filenames: false
+        - id: interrogate
+          # needed to make excludes in pyproject.toml work
+          # see here https://github.com/econchick/interrogate/issues/60#issuecomment-735436566
+          pass_filenames: false

docs/source/_static/interrogate_badge.svg

@@ -46,31 +46,36 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "myst_parser",
-    "nbsphinx",
+    "myst_nb",
+    "sphinxcontrib.bibtex",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
     "sphinx_autodoc_typehints",
 ]
 
-source_suffix = [".rst", ".md"]
+nb_execution_mode = "off"
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".ipynb": "myst-nb",
+    ".myst": "myst-nb",
+}
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 master_doc = "index"
 
+# bibtex config
+bibtex_bibfiles = ["references.bib"]
+bibtex_default_style = "unsrt"
+bibtex_reference_style = "author_year"
+
 # -- intersphinx config -------------------------------------------------------
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "pymc": ("https://www.pymc.io/projects/docs/en/stable/", None),
 }
 
-# -- nbsphinx config ----------------------------------------------------------
-# Opt out of executing the notebooks remotely. This will save time in the remote build
-# process on readthedocs. The notebooks in /docs/notebooks will be parsed/converted,
-# but not re-executed.
-nbsphinx_execute = "never"
-
 # MyST options for working with markdown files.
 # Info about extensions here https://myst-parser.readthedocs.io/en/latest/syntax/optional.html?highlight=math#admonition-directives # noqa: E501
 myst_enable_extensions = [

docs/source/conf.py

@@ -1,10 +1,8 @@
 # Glossary
 
-<div class="admonition note" name="html-admonition">
-<p class="title">Note:</p>
-Some of the definitions have been copied from (or inspired by) various resources, including Reichardt (2019).
-</div>
-
+:::{note}
+Some of the definitions have been copied from (or inspired by) various resources, including {cite:t}`reichardt2019quasi`.
+:::
 
 **ANCOVA:** Analysis of covariance is a simple linear model, typically with one continuous predictor (the covariate) and a catgeorical variable (which may correspond to treatment or control group). In the context of this package, ANCOVA could be useful in pre-post treatment designs, either with or without random assignment. This is similar to the approach of difference in differences, but only applicable with a single pre and post treatment measure.
 
@@ -63,4 +61,6 @@ Data from pretest-posttest NEGD could be analysed using change score analysis or
 **Treatment effect:** The difference in outcomes between what happened after a treatment is implemented and what would have happened (see Counterfactual) if the treatment had not been implemented, assuming everything else had been the same.
 
 ## References
-* Reichardt, C. S. (2019). Quasi-experimentation: A guide to design and analysis. Guilford Publications.
+:::{bibliography}
+:filter: docname in docnames
+:::

docs/source/glossary.md

@@ -7,13 +7,9 @@
    "source": [
     "# ANCOVA for pre/post treatment nonequivalent group designs\n",
     "\n",
-    "<div class=\"alert alert-warning\">\n",
-    "\n",
-    "Warning\n",
-    "\n",
+    ":::{note}\n",
     "This is a preliminary example based on synthetic data. It will hopefully soon be updated with data from a real study.\n",
-    "\n",
-    "</div>\n",
+    ":::\n",
     "\n",
     "In cases where there is just one pre and one post treatment measurement, it we can analyse data from NEGD experiments using an ANCOVA type approach. The basic model is:\n",
     "\n",
@@ -56,6 +52,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -219,13 +216,9 @@
    "source": [
     "## Run the analysis\n",
     "\n",
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note:\n",
-    "\n",
+    ":::{note}\n",
     "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {

docs/source/notebooks/ancova_pymc.ipynb

@@ -7,13 +7,9 @@
    "source": [
     "# Difference in Differences with `pymc` models\n",
     "\n",
-    "<div class=\"alert alert-warning\">\n",
-    "\n",
-    "Warning\n",
-    "\n",
+    ":::{note}\n",
     "This example is in-progress! Further elaboration and explanation will follow soon.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {
@@ -40,6 +36,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -150,13 +147,9 @@
    "source": [
     "## Run the analysis\n",
     "\n",
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note:\n",
-    "\n",
+    ":::{note}\n",
     "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {

docs/source/notebooks/did_pymc.ipynb

@@ -7,15 +7,11 @@
    "source": [
     "# Banking dataset with a `pymc` model\n",
     "\n",
-    "<div class=\"alert alert-warning\">\n",
-    "\n",
-    "Warning\n",
-    "\n",
+    ":::{note}\n",
     "This example is in-progress! Further elaboration and explanation will follow soon.\n",
+    ":::\n",
     "\n",
-    "</div>\n",
-    "\n",
-    "This notebook analyses historic data on banking closures from [Richardson & Troost (2009)](http://masteringmetrics.com/wp-content/uploads/2015/02/Richardson_Troost_2009_JPE.pdf) and used as a case study for a difference in differences analysis in the [Mastering Metrics](http://www.masteringmetrics.com) book. Here, we replicate this analysis, but using Bayesian inference."
+    "This notebook analyses historic data on banking closures from {cite:t}`richardson2009monetary` and used as a case study for a difference in differences analysis in the excellent book [Mastering Metrics](http://www.masteringmetrics.com) {cite:p}`angrist2014mastering`. Here, we replicate this analysis, but using Bayesian inference."
    ]
   },
   {
@@ -49,7 +45,7 @@
    "source": [
     "## Load data\n",
     "\n",
-    "The raw dataset has a `date` columns which is just some uninterpretable number. All we need for our analysis is the `year` column. We also have columns `bib6`, `bio6`, `bib8`, `bio8`. We know that the `6` and `8` represent the 6th and 8th Federal Reserve districts, respectively. I assume `bib` means \"banks in business\", so I'll discard the `bib*` columns. The data is at daily resolution, but we will convert this to yearly resolution. And from what I can tell from Figure 5.2 of the [Mastering Metrics](http://www.masteringmetrics.com) book, they seem to present the _median_ number of banks open per year. Let's load the data up and do those steps."
+    "The raw dataset has a `date` columns which is just some uninterpretable number. All we need for our analysis is the `year` column. We also have columns `bib6`, `bio6`, `bib8`, `bio8`. We know that the `6` and `8` represent the 6th and 8th Federal Reserve districts, respectively. I assume `bib` means \"banks in business\", so I'll discard the `bib*` columns. The data is at daily resolution, but we will convert this to yearly resolution. And from what I can tell from Figure 5.2 of the {cite:t}`angrist2014mastering`, they seem to present the _median_ number of banks open per year. Let's load the data up and do those steps."
    ]
   },
   {
@@ -170,7 +166,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's visualise what we have. This matches up exactly with Figure 5.2 of the [Mastering Metrics](http://www.masteringmetrics.com) book."
+    "Let's visualise what we have. This matches up exactly with Figure 5.2 of the {cite:t}`angrist2014mastering`."
    ]
   },
   {
@@ -395,13 +391,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note:\n",
-    "\n",
+    ":::{note}\n",
     "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {
@@ -636,11 +628,15 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "attachments": {},
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
-   "source": []
+   "source": [
+    "## References\n",
+    ":::{bibliography}\n",
+    ":filter: docname in docnames\n",
+    ":::"
+   ]
   }
  ],
  "metadata": {

docs/source/notebooks/did_pymc_banks.ipynb

@@ -268,13 +268,9 @@
     "\n",
     "We can use `CausalPy`'s API to run this procedure, but using Bayesian inference methods as follows:\n",
     "\n",
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note:\n",
-    "\n",
+    ":::{note}\n",
     "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {

docs/source/notebooks/geolift1.ipynb

@@ -181,13 +181,9 @@
     "\n",
     "In this example we are going to standardize the data. So we have to be careful in how we interpret the inferred regression coefficients, and the posterior predictions will be in this standardized space.\n",
     "\n",
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note:\n",
-    "\n",
+    ":::{note}\n",
     "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {

docs/source/notebooks/its_covid.ipynb

@@ -162,13 +162,9 @@
    "source": [
     "Run the analysis\n",
     "\n",
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note:\n",
-    "\n",
+    ":::{note}\n",
     "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {
@@ -312,13 +308,9 @@
    "source": [
     "As well as the model coefficients, we might be interested in the avarage causal impact and average cumulative causal impact.\n",
     "\n",
-    "<div class=\"alert alert-info\">\n",
-    "\n",
-    "Note\n",
-    "\n",
+    ":::{note}\n",
     "Better output for the summary statistics are in progress!\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {
@@ -405,13 +397,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "<div class=\"alert alert-warning\">\n",
-    "\n",
-    "Warning\n",
-    "\n",
+    ":::{warning}\n",
     "Care must be taken with the mean impact statistic. It only makes sense to use this statistic if it looks like the intervention had a lasting (and roughly constant) effect on the outcome variable. If the effect is transient, then clearly there will be a lot of post-intervention period where the impact of the intervention has 'worn off'. If so, then it will be hard to interpret the mean impacts real meaning.\n",
-    "\n",
-    "</div>"
+    ":::"
    ]
   },
   {

docs/source/notebooks/its_pymc.ipynb

@@ -1,6 +1,7 @@
 {
     "cells": [
         {
+            "attachments": {},
             "cell_type": "markdown",
             "metadata": {},
             "source": [
@@ -42,13 +43,9 @@
             "cell_type": "markdown",
             "metadata": {},
             "source": [
-                "<div class=\"alert alert-info\">\n",
-                "\n",
-                "Note:\n",
-                "\n",
+                ":::{note}\n",
                 "The `random_seed` keyword argument for the PyMC sampler is not neccessary. We use it here so that the results are reproducible.\n",
-                "\n",
-                "</div>"
+                ":::"
             ]
         },
         {