Merge pull request #217 from pymc-labs/glossary

Convert static glossary into a proper interlinked sphinx glossary

Author: drbenvincent

docs/source/glossary.md

@@ -0,0 +1,83 @@
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   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.
+
+   Average treatment effect
+   ATE
+      The average treatement effect across all units.
+
+   Average treatment effect on the treated
+   ATT
+      The average effect of the treatment on the units that recieved it. Also called Treatment on the treated.
+
+   Change score analysis
+      A statistical procedure where the outcome variable is the difference between the posttest and protest scores.
+
+   Comparative interrupted time-series
+   CITS
+      An interrupted time series design with added comparison time series observations.
+
+   Confound
+      Anything besides the treatment which varies across the treatment and control conditions.
+
+   Counterfactual
+      A hypothetical outcome that could or will occur under specific hypothetical circumstances.
+
+   Difference in differences
+   DiD
+      Analysis where the treatment effect is estimated as a difference between treatment conditions in the differences between pre-treatment to post treatment observations.
+
+   Interrupted time series design
+   ITS
+      A quasi-experimental design to estimate a treatment effect where a series of observations are collected before and after a treatment. No control group is present.
+
+   Non-equivalent group designs
+   NEGD
+      A quasi-experimental design where units are assigned to conditions non-randomly, and not according to a running variable (see Regression discontinuity design).
+
+   One-group posttest-only design
+      A design where a single group is exposed to a treatment and assessed on an outcome measure. There is no pretest measure or comparison group.
+
+   Panel data
+      Time series data collected on multiple units where the same units are observed at each time point.
+
+   Pretest-posttest design
+      A quasi-experimental design where the treatment effect is estimated by comparing an outcome measure before and after treatment.
+
+   Quasi-experiment
+      An empirical comparison used to estimate the effects of a treatment where units are not assigned to conditions at random.
+
+   Random assignment
+      Where units are assigned to conditions at random.
+
+   Randomized experiment
+      An emprical comparison used to estimate the effects of treatments where units are assigned to treatment conditions randomly.
+
+   Regression discontinuity design
+      A quasi–experimental comparison to estimate a treatment effect where units are assigned to treatment conditions based on a cut-off score on a quantitative assignment variable (aka running variable).
+
+   Sharp regression discontinuity design
+      A Regression discontinuity design where allocation to treatment or control is determined by a sharp threshold / step function.
+
+   Synthetic control
+      The synthetic control method is a statistical method used to evaluate the effect of an intervention in comparative case studies. It involves the construction of a weighted combination of groups used as controls, to which the treatment group is compared.
+
+   Treatment on the treated effect
+   TOT
+      The average effect of the treatment on the units that recieved it. Also called the average treatment effect on the treated (ATT).
+
+   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.
+
+   Wilkinson notation
+      A notation for describing statistical models :footcite:p:`wilkinson1973symbolic`.
+
+
+References
+----------
+.. footbibliography::

docs/source/glossary.rst

@@ -126,7 +126,7 @@ Documentation outline
 .. toctree::
    :titlesonly:
 
-   glossary.md
+   glossary
 
 .. toctree::
    :caption: Examples

docs/source/index.rst

@@ -11,7 +11,7 @@
     "This is a preliminary example based on synthetic data. It will hopefully soon be updated with data from a real study.\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",
+    "In cases where there is just one pre and one post treatment measurement, it we can analyse data from {term}`NEGD` experiments using an {term}`ANCOVA` type approach. The basic model is:\n",
     "\n",
     "$$\n",
     "post_i = \\beta_0 + (\\beta_1 \\cdot T_i) + (\\beta_2 \\cdot pre_i) + \\epsilon_i\n",

docs/source/notebooks/ancova_pymc.ipynb

@@ -513,7 +513,7 @@
    "source": [
     "## Analysis 2 - DiD with multiple pre/post observations\n",
     "\n",
-    "Now we'll do a difference in differences analysis of the full dataset. This approach has similarities to CITS (Comparative Interrupted Time Series) with a single control over time. Although slightly abitrary, we distinguish between the two techniques on whether there is enough time series data for CITS to capture the time series patterns."
+    "Now we'll do a difference in differences analysis of the full dataset. This approach has similarities to {term}`CITS` (Comparative Interrupted Time-Series) with a single control over time. Although slightly abitrary, we distinguish between the two techniques on whether there is enough time series data for CITS to capture the time series patterns."
    ]
   },
   {
@@ -721,7 +721,7 @@
   "kernelspec": {
    "display_name": "CausalPy",
    "language": "python",
-   "name": "causalpy"
+   "name": "python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -733,12 +733,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.4"
-  },
-  "vscode": {
-   "interpreter": {
-    "hash": "46d31859cc45aa26a1223a391e7cf3023d69984b498bed11e66c690302b7e251"
-   }
+   "version": "3.10.8"
   }
  },
  "nbformat": 4,

docs/source/notebooks/did_pymc_banks.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# Bayesian geolift with CausalPy\n",
     "\n",
-    "This notebook covers how to use `CausalPy`'s Bayesian synthetic control functionality to assess 'geolift'. Our hypothetical scenario is:\n",
+    "This notebook covers how to use `CausalPy`'s Bayesian {term}`synthetic control` functionality to assess 'geolift'. Our hypothetical scenario is:\n",
     "\n",
     "> We are a data scientist within a company that operates over Europe. We have been given a historical dataset of sales volumes, in units of 1000's. The data is broken down by country and was collected at weekly frequency. We have data for the past 4 years. \n",
     "\n",

docs/source/notebooks/geolift1.ipynb

@@ -7,7 +7,7 @@
    "source": [
     "# The effects of Brexit\n",
     "\n",
-    "The aim of this notebook is to estimate the causal impact of Brexit upon the UK's GDP. This will be done using the synthetic control approch. As such, it is similar to the policy brief \"What can we know about the cost of Brexit so far?\" {cite:p}`brexit2022policybrief` from the Center for European Reform. That approach did not use Bayesian estimation methods however.\n",
+    "The aim of this notebook is to estimate the causal impact of Brexit upon the UK's GDP. This will be done using the {term}`synthetic control` approch. As such, it is similar to the policy brief \"What can we know about the cost of Brexit so far?\" {cite:p}`brexit2022policybrief` from the Center for European Reform. That approach did not use Bayesian estimation methods however.\n",
     "\n",
     "I did not use the GDP data from the above report however as it had been scaled in some way that was hard for me to understand how it related to the absolute GDP figures. Instead, GDP data was obtained courtesy of Prof. Dooruj Rambaccussing. Raw data is in units of billions of USD."
    ]
@@ -215,13 +215,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>"
+    ":::"
    ]
   },
   {

docs/source/notebooks/sc_pymc_brexit.ipynb

@@ -40,3 +40,14 @@ @article{carpenter2009effect
   year={2009},
   publisher={American Economic Association}
 }
+
+@article{wilkinson1973symbolic,
+  title={Symbolic description of factorial models for analysis of variance},
+  author={Wilkinson, GN and Rogers, CE},
+  journal={Journal of the Royal Statistical Society Series C: Applied Statistics},
+  volume={22},
+  number={3},
+  pages={392--399},
+  year={1973},
+  publisher={Oxford University Press}
+}