Fix HTML Outline rendering (#188)

* fixed outline rendering * fixes outline links in mediation notebook. * fixes outline and links for backdoor notebook. * fixes outline links in cevae notebook. * fixes slc notebook outline links. * adds outline back into deep scm notebook. * address remaining reference issues, building now with now warnings --------- Co-authored-by: Andy Zane <andy@basis.ai>
BasisResearch · Jul 8, 2023 · 5dcb6e8 · 5dcb6e8
1 parent f7fbe33
commit 5dcb6e8
Show file tree

Hide file tree

Showing 6 changed files with 1,226 additions and 1,230 deletions.
diff --git a/docs/source/backdoor.ipynb b/docs/source/backdoor.ipynb
diff --git a/docs/source/cevae.ipynb b/docs/source/cevae.ipynb
@@ -15,28 +15,20 @@
    "source": [
     "## Outline\n",
     "\n",
-    "[Setup](#setup)\n",
-    "\n",
-    "[Overview: Systematically adjusting for observed confounding](#overview-systematically-adjusting-for-observed-confounding)\n",
-    "- [Task: Treatment effect estimation with observational data](#task-treatment-effect-estimation-with-observational-data)\n",
-    "- [Challenge: Confounding](#challenge-confounding)\n",
-    "- [Assumptions: All latent confounders influence at least one \"proxy\" covariate](#assumptions-all-latent-confounders-influence-at-least-one-proxy-covariate)\n",
-    "- [Intuition: Adjusting for confounding via proxies](#intuition-adjusting-for-confounding-via-proxies)\n",
-    "\n",
-    "[Example: Synthetic data](#example-synthetic-data)\n",
-    "\n",
-    "[Causal Probabilistic Program](#causal-probabilistic-program)\n",
-    "- [Model Description](#model-description)\n",
-    "- [Prior Description](#prior-description)\n",
-    "\n",
-    "[Causal Query: conditional average treatment effect](#causal-query-average-treatment-effect-ate)\n",
-    "- [Fit parameter via maximum likelihood](#fit-parameters-via-maximum-likelihood)\n",
-    "\n",
-    "[Causal Inference as Probabilistic Inference](#causal-inference-as-probabilistic-inference)\n",
-    "- [Maximum Likelihood Inference](#maximum-likelihood-inference)\n",
-    "- [Maximum a Posteriori Inference](#maximum-a-posteriori-inference)\n",
-    "\n",
-    "[Results](#results)\n"
+    "- [Setup](#setup)\n",
+    "- [Overview: Proxy variables and latent confounders](#overview:-proxy-variables-and-latent-confounders)\n",
+    "    - [Task: Treatment effect estimation with observational data](#task:-treatment-effect-estimation-with-observational-data)\n",
+    "    - [Challenge: Confounding](#challenge:-confounding)\n",
+    "    - [Assumptions: All latent confounders influence at least one \"proxy\" covariate](#assumptions:-all-latent-confounders-influence-at-least-one-\\\"proxy\\\"-covariate)\n",
+    "    - [Intuition: Adjusting for confounding via proxies](#intuition:-adjusting-for-confounding-via-proxies)\n",
+    "- [Example: Synthetic data](#example:-synthetic-data)\n",
+    "- [Causal Probabilistic Program](#causal-probabilistic-program)\n",
+    "    - [Model Description](#model-description)\n",
+    "    - [Prior Description](#prior-description)\n",
+    "- [Causal Query: conditional average treatment effect (CATE)](#causal-query:-conditional-average-treatment-effect-\\(CATE\\))\n",
+    "    - [Fit parameter via maximum likelihood](#fit-parameters-via-maximum-likelihood)\n",
+    "- [Causal Inference as Probabilistic Inference](#causal-inference-as-probabilistic-inference)\n",
+    "- [Results](#results)\n"
    ]
   },
   {
@@ -1134,7 +1126,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.9"
+   "version": "3.9.15"
   },
   "vscode": {
    "interpreter": {

diff --git a/docs/source/deepscm.ipynb b/docs/source/deepscm.ipynb
@@ -8,6 +8,39 @@
     "# Example: Deep structural causal model counterfactuals"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Outline\n",
+    "\n",
+    "- [Setup](#setup)\n",
+    "- [Overview: Counterfactual estimation with normalizing flows](#overview:-counterfactual-estimation-with-normalizing-flows)\n",
+    "    - [Task: Counterfactual inference](#task:-counterfactual-inference)\n",
+    "    - [Challenge: Holding exogenous noise fixed with tractable likelihoods](#challenge:-holding-exogenous-noise-fixed-with-tractable-likelihoods)\n",
+    "    - [Assumptions: All confounders observed. Unique mapping from structural functions to joint probability distributions.](#assumptions:-all-confounders-observed.-unique-mapping-from-structural-functions-to-joint-probability-distributions.)\n",
+    "    - [Intuition: Deep invertible neural networks using Normalizing Flows](#intuition:-deep-invertible-neural-networks-using-normalizing-flows)\n",
+    "    - [Caveat: Strong assumptions and identifiability](#caveat:-strong-assumptions-and-identifiability)\n",
+    "- [Example: Morpho-MNIST](#example:-morpho-mnist)\n",
+    "    - [Variables](#variables)\n",
+    "    - [Motivation](#motivation)\n",
+    "    - [Dataset](#dataset)\n",
+    "- [Model: deep structural causal model](#model:-deep-structural-causal-model)\n",
+    "- [Causal Query: counterfactual data generation](#causal-query:-counterfactual-data-generation)\n",
+    "- [References](#references)\n"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Setup"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -127,7 +160,7 @@
     "\n",
     "Like many of the examples thus far, in this example we will assume that all confounders between endogenous variables are observed. See the [backdoor](backdoor.ipynb) example for a more in-depth description of this assumption.\n",
     "\n",
-    "Additionally, estimating counterfactual quantities requires additional assumptions. Just as many interventional distributions can map to the same observational distribution (see the [tutorial](tutorial.ipynb)), so too can many counterfactual distributions map to the same interventional distribution. Above we chose a single reparameterization of the conditional probability distribution $P(Y_i|T_i)$ in terms of structural functions, but that was just one particular choice, and other choices can often result in different counterfactual conclusions. In general, to disambiguate between multiple plausible structural causal models we must either assume a family structural causal models a priori, either by specifying a parameteric family as we do here, or by making more declarative assumptions about structural functions (e.g. structural functions are monotonic \\[Pearl 2009\\]). Importantly, the use of Normalizing flows as the parametric family in this case is both an innovation **and** an assumption, implicitly restricting the space of structural functions a priori."
+    "Additionally, estimating counterfactual quantities requires additional assumptions. Just as many interventional distributions can map to the same observational distribution (see the [tutorial](tutorial_i.ipynb)), so too can many counterfactual distributions map to the same interventional distribution. Above we chose a single reparameterization of the conditional probability distribution $P(Y_i|T_i)$ in terms of structural functions, but that was just one particular choice, and other choices can often result in different counterfactual conclusions. In general, to disambiguate between multiple plausible structural causal models we must either assume a family structural causal models a priori, either by specifying a parameteric family as we do here, or by making more declarative assumptions about structural functions (e.g. structural functions are monotonic \\[Pearl 2009\\]). Importantly, the use of Normalizing flows as the parametric family in this case is both an innovation **and** an assumption, implicitly restricting the space of structural functions a priori."
    ]
   },
   {

diff --git a/docs/source/mediation.ipynb b/docs/source/mediation.ipynb
@@ -13,28 +13,21 @@
    "source": [
     "## Outline\n",
     "\n",
-    "[Setup](#setup)\n",
-    "\n",
-    "[Overview: mediation analysis](#overview:-mediation-analysis)\n",
-    "- [Task: identify the (in)direct causal role of a variable](#task-identify-the-indirect-causal-role-of-a-variable)\n",
-    "- [Challenge: conditioning on mediators might open paths](#challenge-conditioning-on-mediators-might-open-paths)\n",
-    "- [Definitions](#definitions)\n",
-    "- [Assumptions](#assumptions)\n",
-    "\n",
-    "[Example: the effect of family interventions on future substance use](#example-the-effect-of-family-interventions-on-future-substance-use)\n",
-    "- [Variables](#variables)\n",
-    "- [Motivations](#motivations)\n",
-    "- [Source](#source)\n",
-    "  \n",
-    "[Causal Probabilistic Program](#causal-probabilistic-program)\n",
-    "- [Model description](#model-description)\n",
-    "- [Prior description](#prior-description)\n",
-    "\n",
-    "[Causal Query: average natural direct effect (ANDE)](#causal-query-average-natural-direct-effect-ande)\n",
-    "\n",
-    "[Causal Inference](#causal-inference)\n",
-    "\n",
-    "[Results](#results)\n"
+    "- [Setup](#setup)\n",
+    "- [Overview: mediation analysis](#overview:-mediation-analysis)\n",
+    "    - [Task: identify the (in)direct causal role of a variable](#task:-identify-the-\\(in\\)direct-causal-role-of-a-variable)\n",
+    "    - [Challenge: conditioning on mediators might open paths](#challenge:-mere-conditioning-may-fail-to-isolate-a-path)\n",
+    "    - [Definitions](#definitions)\n",
+    "    - [Assumptions](#assumptions)\n",
+    "- [Example: the effect of family interventions on future substance use](#example:-the-effect-of-family-interventions-on-future-substance-use)\n",
+    "    - [Variables](#variables)\n",
+    "    - [Motivations](#motivations)\n",
+    "    - [Source](#source)\n",
+    "- [Causal Probabilistic Program](#causal-probabilistic-program)\n",
+    "    - [Model description](#model-description)\n",
+    "- [Causal Query: average natural direct effect (ANDE)](#causal-query:-average-natural-direct-effect-\\(ANDE\\))\n",
+    "- [Causal Inference as Probabilistic Inference](#causal-inference-as-probabilistic-inference)\n",
+    "- [Results](#results)\n"
    ]
   },
   {
@@ -1195,7 +1188,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.9"
+   "version": "3.9.15"
   },
   "vscode": {
    "interpreter": {

diff --git a/docs/source/slc.ipynb b/docs/source/slc.ipynb
@@ -13,32 +13,24 @@
    "source": [
     "## Outline\n",
     "\n",
-    "[Setup](#setup)\n",
-    "\n",
-    "[Overview: Observational Causal Inference with Grouped Data](#overview-observational-causal-inference-with-grouped-data)\n",
-    "- [Task: Treatment effect estimation with observational data](#task-treatment-effect-estimation-with-observational-data)\n",
-    "- [Challenge: Confounding](#challenge-confounding)\n",
-    "- [Assumptions: All latent confounders shared within an object](#assumptions-all-latent-confounders-shared-within-an-object)\n",
-    "- [Intuition: Statistically adjusting for confounding](#intuition-statistically-adjusting-for-confounding)\n",
-    "\n",
-    "[Example: Electric Company Education Study](#example-electric-company-education-study)\n",
-    "- [Variables](#variables)\n",
-    "- [Motivation](#motivation)\n",
-    "- [Source](#source)\n",
-    "\n",
-    "[Causal Probabilistic Program](#causal-probabilistic-program)\n",
-    "- [Model Description](#model-description)\n",
-    "- [Prior Description](#prior-description)\n",
-    "- [Informal Prior Predictive Check: Visualizing Samples](#informal-prior-predictive-check---visualizing-samples)\n",
-    "\n",
-    "[Causal Query: average treatment effect](#causal-query-average-treatment-effect-ate)\n",
-    "\n",
-    "[Causal Inference as Probabilistic Inference](#causal-inference-as-probabilistic-inference)\n",
-    "- [Maximum Likelihood Inference](#maximum-likelihood-inference)\n",
-    "- [Maximum a Posteriori Inference](#maximum-a-posteriori-inference)\n",
-    "- [Gaussian Mean Field Variational Inference](#gaussian-mean-field-variational-inference)\n",
-    "\n",
-    "[Results](#results)\n"
+    "- [Setup](#setup)\n",
+    "- [Overview: Observational Causal Inference with Grouped Data](#overview:-observational-causal-inference-with-grouped-data)\n",
+    "    - [Task: Treatment effect estimation with observational data](#task:-treatment-effect-estimation-with-observational-data)\n",
+    "    - [Challenge: Confounding](#challenge:-confounding)\n",
+    "    - [Assumptions: All latent confounders shared within an object](#assumptions:-all-latent-confounders-shared-within-an-object)\n",
+    "    - [Intuition: Statistically adjusting for confounding](#intuition:-statistically-adjusting-for-confounding)\n",
+    "- [Example: Electric Company Education Study](#example:-electric-company-education-study)\n",
+    "    - [Variables](#variables)\n",
+    "    - [Motivation](#motivation)\n",
+    "    - [Source](#source)\n",
+    "- [Causal Probabilistic Program](#causal-probabilistic-program)\n",
+    "    - [Model Description](#model-description)\n",
+    "    - [Prior Description](#prior-description)\n",
+    "    - [Informal Prior Predictive Check: Visualizing Samples](#informal-prior-predictive-check---visualizing-samples)\n",
+    "- [Causal Query: average treatment effect (ATE)](#causal-query:-average-treatment-effect-\\(ATE\\))\n",
+    "- [Causal Inference as Probabilistic Inference](#causal-inference-as-probabilistic-inference)\n",
+    "    - [Gaussian Mean Field Variational Inference](#gaussian-mean-field-variational-inference)\n",
+    "- [Results](#results)\n"
    ]
   },
   {
@@ -182,7 +174,7 @@
    "source": [
     "### Motivation\n",
     "\n",
-    "Understanding the effect of the education program may be useful for education policymakers who may wish to provide additional funding for similar programs in the future. In addition, curriculum designers could use these study results to better align classroom activity with educational outcome goals. Both of these use-cases require causal insight, as changes to policy or curriculum are best thought of as an intervention. See our [Introductory Tutorial](tutorial_1.ipynb) for a more in-depth discussion of the difference between association and intervention."
+    "Understanding the effect of the education program may be useful for education policymakers who may wish to provide additional funding for similar programs in the future. In addition, curriculum designers could use these study results to better align classroom activity with educational outcome goals. Both of these use-cases require causal insight, as changes to policy or curriculum are best thought of as an intervention. See our [Introductory Tutorial](tutorial_i.ipynb) for a more in-depth discussion of the difference between association and intervention."
    ]
   },
   {
@@ -1130,6 +1122,9 @@
   },
   {
    "cell_type": "markdown",
+   "metadata": {
+    "collapsed": false
+   },
    "source": [
     "## References\n",
     "\n",
@@ -1144,10 +1139,7 @@
     "Ball, Samuel. \"Reading with Television: An Evaluation of The Electric Company. A Report to the Children's Television Workshop. Volumes 1 and 2.\" (1973).\n",
     "\n",
     "Witty, Sam, Kenta Takatsu, David Jensen, and Vikash Mansinghka. “Causal Inference Using Gaussian Processes with Structured Latent Confounders.” In International Conference on Machine Learning, 10313–23. PMLR, 2020.\n"
-   ],
-   "metadata": {
-    "collapsed": false
-   }
+   ]
   }
  ],
  "metadata": {
@@ -1166,7 +1158,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.9"
+   "version": "3.9.15"
   },
   "vscode": {
    "interpreter": {

diff --git a/docs/source/tutorial_i.ipynb b/docs/source/tutorial_i.ipynb
@@ -25,37 +25,30 @@
    "metadata": {},
    "source": [
     "## Outline\n",
-    "[Introduction](#causal-probabilistic-programming-without-tears)\n",
-    "\n",
-    "[Outline](#outline)\n",
-    "\n",
-    "[Observation 1: Causal Models are Probabilistic Programs](#observation-1-causal-models-are-probabilistic-programs)\n",
-    "- [Defining a Causal Model](#defining-a-causal-model)\n",
-    "- [Simulating Observational Data](#simulating-observational-data-with-fixed-parameters)\n",
-    "- [Applying an Intervention](#applying-an-intervention)\n",
-    "- [Simulating Interventional Data](#simulating-interventional-data-with-fixed-parameters)\n",
-    "- [Transforming Causal Models using Causal Pyro](#transforming-causal-models-using-causal-pyro---do)\n",
-    "\n",
-    "[Observation 2: Causal Uncertainty is Probabilistic Uncertainty](#observation-2-causal-uncertainty-is-probabilistic-uncertainty)\n",
-    "- [Adding Uncertainty over Model Parameters](#adding-uncertainty-over-model-parameters)\n",
-    "- [Simulating Observational Data with Uncertain Parameters](#simulating-observational-data-with-uncertain-parameters)\n",
-    "- [Simulating Interventional Data with Uncertain Parameters](#simulating-interventional-data-with-uncertain-parameters)\n",
-    "- [Adding Uncertainty over Model Structure](#adding-uncertainty-over-model-structure)\n",
-    "- [Simulating Observational Data with Uncertain Structure and Parameters](#simulating-observational-data-with-uncertain-structure-and-parameters)\n",
-    "- [Simulating Interventional Data with Uncertain Structure and Parameters](#simulating-interventional-data-with-uncertain-structure-and-parameters)\n",
-    "\n",
-    "[Observation 3: Causal Inference is Probabilistic Inference](#observation-3-causal-inference-is-probabilistic-inference)\n",
-    "- [Automatically Constructing Counterfactual Worlds](#automatically-constructing-counterfactual-worlds---twinworldcounterfactual)\n",
-    "- [Generating Synthetic Data](#generating-synthetic-data)\n",
-    "- [Conditioning the Causal Model on Observational Data](#conditioning-the-causal-model-on-observational-data)\n",
-    "- [Using Variational Inference for Bayesian Causal Inference](#using-variational-inference-for-bayesian-causal-inference)\n",
-    "- [Simulating Interventional Data from the Approximate Posterior](#simulating-interventional-data-from-the-approximate-posterior)\n",
-    "\n",
-    "[Recap](#recap)\n",
-    "\n",
-    "[Causal Bayesian Workflow](#a-causal-bayesian-workflow)\n",
-    "\n",
-    "[References](#references)"
+    "- [Introduction](#causal-probabilistic-programming-without-tears)\n",
+    "- [Outline](#outline)\n",
+    "- [Observation 1: Causal Models are Probabilistic Programs](#observation-1:-causal-models-are-probabilistic-programs)\n",
+    "    - [Defining a Causal Model](#defining-a-causal-model)\n",
+    "    - [Simulating Observational Data](#simulating-observational-data-with-fixed-parameters)\n",
+    "    - [Applying an Intervention](#applying-an-intervention)\n",
+    "    - [Simulating Interventional Data](#simulating-interventional-data-with-fixed-parameters)\n",
+    "    - [Transforming Causal Models using Causal Pyro](#transforming-causal-models-using-causal-pyro---do)\n",
+    "- [Observation 2: Causal Uncertainty is Probabilistic Uncertainty](#observation-2:-causal-uncertainty-is-probabilistic-uncertainty)\n",
+    "    - [Adding Uncertainty over Model Parameters](#adding-uncertainty-over-model-parameters)\n",
+    "    - [Simulating Observational Data with Uncertain Parameters](#simulating-observational-data-with-uncertain-parameters)\n",
+    "    - [Simulating Interventional Data with Uncertain Parameters](#simulating-interventional-data-with-uncertain-parameters)\n",
+    "    - [Adding Uncertainty over Model Structure](#adding-uncertainty-over-model-structure)\n",
+    "    - [Simulating Observational Data with Uncertain Structure and Parameters](#simulating-observational-data-with-uncertain-structure-and-parameters)\n",
+    "    - [Simulating Interventional Data with Uncertain Structure and Parameters](#simulating-interventional-data-with-uncertain-structure-and-parameters)\n",
+    "- [Observation 3: Causal Inference is Probabilistic Inference](#observation-3:-causal-inference-is-probabilistic-inference)\n",
+    "    - [Automatically Constructing Counterfactual Worlds](#automatically-constructing-counterfactual-worlds---twinworldcounterfactual)\n",
+    "    - [Generating Synthetic Data](#generating-synthetic-data)\n",
+    "    - [Conditioning the Causal Model on Observational Data](#conditioning-the-causal-model-on-observational-data)\n",
+    "    - [Using Variational Inference for Bayesian Causal Inference](#using-variational-inference-for-bayesian-causal-inference)\n",
+    "    - [Simulating Interventional Data from the Approximate Posterior](#simulating-interventional-data-from-the-approximate-posterior)\n",
+    "- [Recap](#recap)\n",
+    "- [Causal Bayesian Workflow](#a-causal-bayesian-workflow)\n",
+    "- [References](#references)"
    ]
   },
   {
@@ -1924,11 +1917,6 @@
     "\n",
     "Tran, Dustin, et al. \"Model criticism for bayesian causal inference.\" arXiv preprint arXiv:1610.09037 (2016)."
    ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": []
   }
  ],
  "metadata": {