L3_weighting_matching.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\n",
    "\\newcommand{P}[1]{\\mathrm{P}\\left( #1 \\right)}\n",
    "\\newcommand{Pc}[2]{\\mathrm{P}\\left( #1 \\mid #2 \\right)}\n",
    "\\newcommand{Ec}[2]{\\mathrm{E}\\left( #1 \\mid #2 \\right)}\n",
    "\\newcommand{In}[2]{ #1 \\perp\\!\\!\\!\\perp #2}\n",
    "\\newcommand{Cin}[3]{ #1 \\perp\\!\\!\\!\\perp #2 \\, | \\, #3}\n",
    "\\newcommand{do}[1]{\\mathrm{do}\\left( #1 \\right)}\n",
    "\\newcommand{\\ci}{\\perp\\!\\!\\!\\perp}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# More on Counterfactual Models: Modeling Aproaches\n",
    "\n",
    "Day 3 Module 3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Matching Based Methods\n",
    "\n",
    "We have seen in our smoking study example the usefulness of regression based method in estimating the causal effect ATE. \n",
    "\n",
    "In this case the method has done well in identifying the correct ATE - which is good, but the data generating process was specifically designed to meet the assumption on the model form. We have already seen a case where the regression based method failed. In fact, this happens fairly common."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import division\n",
    "from sklearn.preprocessing import PolynomialFeatures\n",
    "from causalinference import CausalModel\n",
    "\n",
    "import numpy as np\n",
    "np.warnings.filterwarnings('ignore')\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "import seaborn as sns\n",
    "\n",
    "sns.set_style(\"whitegrid\")\n",
    "sns.set_palette(\"colorblind\")\n",
    "\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let us look at the following example, where we have nonlinear relationship:\n",
    "\n",
    "Now for subject $i$ ($i=1,\\cdots,1000$), we generate \n",
    "\n",
    "* the confounder $X_i \\sim N(0,1)$;\n",
    "* binary treatment indicator $A$ from $\\text{logit}[\\Pc{A_i=1}{X_i}]= 0.5 + 0.6X_i$;\n",
    "* the (true) counterfactuals: \n",
    "    - <font color='blue'>$Y^0_i = 2X_i^2 + \\epsilon_i$</font>\n",
    "    - <font color='blue'>$Y^1_i = 3 - 2I(X_i<1) + 2X_i^2 + \\epsilon_i$</font>\n",
    "    - where $\\epsilon_i \\sim N(0,0.3^2)$\n",
    "* the observed outcome $Y_i = Y^1_i \\times A_i + Y^0_i \\times (1 - A_i)$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.axes._subplots.AxesSubplot at 0x13b5f40b588>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x13b5f154080>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "\"\"\"\n",
    "Data Example 2\n",
    "  \n",
    "\"\"\"\n",
    "n_samples = 1000\n",
    "X = np.random.normal(size=n_samples)\n",
    "p_a = np.exp(0.5 + 0.6*X)/(1 + np.exp(0.5 + 0.6*X))\n",
    "A = np.random.binomial(n=1, p=p_a, size=n_samples)\n",
    "eY = 0.3 * np.random.normal(size=n_samples)\n",
    "Y0 = 2 * X * X + eY\n",
    "Y1 = np.where(X < 1, Y0+1, Y0+3)\n",
    "Y = np.where(A == 0, Y0, Y1)\n",
    "data_example2 = pd.DataFrame({\"X\":X, \"A\":A, \"Y\":Y, \"Y0\":Y0, \"Y1\":Y1})\n",
    "data_example2.plot.scatter(x=\"X\", y=\"Y\", c=\"A\", cmap=\"rainbow\", colorbar=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Estimated Association: 1.188 (0.367)\n",
      "Simulated ATE: 1.318\n",
      "Simulated ATC: 1.145\n",
      "Simulated ATT: 1.420\n"
     ]
    }
   ],
   "source": [
    "ctrl_grp = data_example2[data_example2.A == 0]\n",
    "trt_grp = data_example2[data_example2.A == 1]\n",
    "alpha = trt_grp.Y.mean() - ctrl_grp.Y.mean()\n",
    "alpha_err = 1.96 * np.sqrt(\n",
    "        trt_grp.Y.var() / trt_grp.shape[0] + \n",
    "        ctrl_grp.Y.var() / ctrl_grp.shape[0])\n",
    "print(\"Estimated Association: {:.3f}\".format(alpha), \"({:.3f})\".format(alpha_err))\n",
    "\n",
    "\n",
    "theta = data_example2.Y1.mean() - data_example2.Y0.mean()\n",
    "print(\"Simulated ATE: {:.3f}\".format(theta))\n",
    "theta1 = ctrl_grp.Y1.mean() - ctrl_grp.Y0.mean()\n",
    "print(\"Simulated ATC: {:.3f}\".format(theta1))\n",
    "theta2 = trt_grp.Y1.mean() - trt_grp.Y0.mean()\n",
    "print(\"Simulated ATT: {:.3f}\".format(theta2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: OLS\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      1.311      0.199      6.585      0.000      0.921      1.701\n",
      "           ATC      0.243      0.210      1.156      0.248     -0.169      0.654\n",
      "           ATT      1.944      0.227      8.546      0.000      1.498      2.390\n",
      "\n"
     ]
    }
   ],
   "source": [
    "cm = CausalModel(\n",
    "    Y=data_example2.Y.values, \n",
    "    D=data_example2.A.values, \n",
    "    X=data_example2.X.values)\n",
    "\n",
    "cm.est_via_ols()\n",
    "\n",
    "print(cm.estimates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Matching Based Method\n",
    "\n",
    "Usually this can be overcome by using more powerful estimators . A simple, non-parametric approach, is the technique of [matching](https://en.wikipedia.org/wiki/Matching_%28statistics%29). The idea is to find for each sample which received the treatment, a similar samples which did not receive the treatment, and to directly compare these values. Exactly what you mean by \"similar\" will depend on your specific usecase.\n",
    "\n",
    "In our simple example, this means we use a matched observed outcome to imput a missing counterfactual:\n",
    "\n",
    "| index $i$ | $X_i$ | $A_i$ | $Y_i$ | $Y_i^0$ (matching) | $Y_i^1$ (matching) |\n",
    "| --- | --- | --- | --- | --- | --- | \n",
    "| 1 | 0 | 0 | 4 | <font color='red'>$Y_1$</font> | <font color='green'>$Y_4$</font> |\n",
    "| 2 | 0 | 0 | 3 | <font color='red'>$Y_2$</font> | <font color='green'>$Y_4$</font> |\n",
    "| 3 | 0 | 0 | 5 | <font color='red'>$Y_3$</font> | <font color='green'>$Y_4$</font> |\n",
    "| 4 | 0 | 1 | 8 | <font color='green'>$Y_1$</font> | <font color='red'>$Y_4$</font> |\n",
    "| 5 | 1 | 0 | 2 | <font color='red'>$Y_5$</font> | <font color='green'>$Y_7$</font> |\n",
    "| 6 | 1 | 0 | 4 | <font color='red'>$Y_6$</font> | <font color='green'>$Y_7$</font> |\n",
    "| 7 | 1 | 1 | 8 | <font color='green'>$Y_5$</font> | <font color='red'>$Y_7$</font> |\n",
    "| 8 | 1 | 1 | 6 | <font color='green'>$Y_5$</font> | <font color='red'>$Y_8$</font> |\n",
    "\n",
    "For the smoking example, the package `causalinference` implements matching by selecting for each unit, with replacement, the most similar unit from the other treatment group and using the difference between these two units to calculate the ATE. By default, the choice of match is chosen to be the nearest neighbour in covariate space $X$, with the distances weighted by inverse variance of each dimension.\n",
    "\n",
    "There are options to change the number of units compared and the weighting of each dimension in the match. For more details, see the [documentation](http://laurence-wong.com/software/matching).\n",
    "\n",
    "We can compute the matching estimate with the following code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: Matching\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      1.322      0.075     17.572      0.000      1.174      1.469\n",
      "           ATC      1.085      0.095     11.367      0.000      0.898      1.272\n",
      "           ATT      1.462      0.082     17.864      0.000      1.302      1.623\n",
      "\n"
     ]
    }
   ],
   "source": [
    "cm = CausalModel(\n",
    "    Y=data_example2.Y.values, \n",
    "    D=data_example2.A.values, \n",
    "    X=data_example2.X.values)\n",
    "\n",
    "cm.est_via_matching()\n",
    "\n",
    "print(cm.estimates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The confidence intervals around our estimate now contain the true ATE."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The OLS estimator fails to capture the true effect, while the matching based estimator yields the correct estimation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Propensity Score\n",
    "\n",
    "For dichotomous treatments, we denote the 'true' propensity score as\n",
    "$e_i=e(\\boldsymbol{X}_i)=\\Pc{A_i=1}{X_{1i}},X_{2i},\\cdots,X_{pi}$.\n",
    "\n",
    "The propensity score has two fundamental properties in causal inference:\n",
    "* **Balancing property**: Treatment assignment is conditionally independent of the covariates given the propensity score. \n",
    "    - $A_i\\ci \\boldsymbol{X}_i | e(\\boldsymbol{X}_i)$ (sufficient dimension reduction)\n",
    "* **Unconfoundedness**: Under conditional exchangeability, the counterfactual outcomes are conditionally independent given the propensity score: \n",
    "    - $Y_i^a\\ci A_i | e(\\boldsymbol{X}_i)$ for $a=0,1$\n",
    "\n",
    "### Balancing Scores\n",
    "In fact, propensity score is a special case of a more generally defined score function -- Balancing Score\n",
    "\n",
    "Any function $b(\\boldsymbol{X})$ of $\\boldsymbol{X}$ satisfies $A \\ci \\boldsymbol{X}\\,|\\,b(\\boldsymbol{X})$ is called a balancing score. \n",
    "\n",
    "**Theorem**:  A function $b(\\boldsymbol{X})$ is a balancing score if and only if $b(\\boldsymbol{X})$ is “finer” than $e(\\boldsymbol{X})$ in the sense that $e(\\boldsymbol{X})=f(b(\\boldsymbol{X}))$ for some function $f$. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inverse Propensity Score Weighting (Inverse Probability Weighting, IPW)\n",
    "\n",
    "Remember that the problem of measuring causal inference is that we want to know the quantity $E[Y^{a}]$, but we only have access to samples from $E[Y^{a}|A=a]$.\n",
    "\n",
    "The density of a potential outcome can be expanded to give\n",
    "\n",
    "$P(Y^{a}) = P(Y^{a}| A = a)P(A = a)$\n",
    "\n",
    "This suggests that we can estimate the expectation \n",
    "\n",
    "$E[Y^{a}] = E[\\frac{Y^{a}}{P(A = a|X)}P(A=a|X)] = E[\\frac{Y^{a}}{P(A=a|X)}|A=a, X]$\n",
    "\n",
    "So if we weight each point by it's inverse propensity, we can recover the potential outcomes. The result is the [inverse propensity score weight estimator](https://en.wikipedia.org/wiki/Inverse_probability_weighting):\n",
    "\n",
    "$\\theta_{ipw} = \\frac{1}{N}\\left(\\sum_{i \\in 1} \\frac{Y_{i}}{\\hat{e}(X_{i})} - \\sum_{i \\in 0} \\frac{Y_{i}}{1 - \\hat{e}(X_{i})}\\right)$\n",
    "\n",
    "\n",
    "In our simple example, this means we weight the non-missing counterfactuals to represent the missing counterfactuals:\n",
    "\n",
    "$\\Pc{A_i=1}{X_i=0} = 1/4 \\\\\n",
    " \\Pc{A_i=0}{X_i=0} = 3/4 \\\\\n",
    " \\Pc{A_i=1}{X_i=1} = 1/2 \\\\\n",
    " \\Pc{A_i=0}{X_i=1} = 1/2$, \n",
    " \n",
    "thus we have\n",
    "\n",
    "| index $i$ | $X_i$ | $A_i$ | $Y_i$ | $Y_i^0$ (weighting) | $Y_i^1$ (weighting) |\n",
    "| --- | --- | --- | --- | --- | --- | \n",
    "| 1 | 0 | 0 | 4 | <font color='red'>$Y_1$</font>$\\times$<font color='green'>$\\frac{4}{3}$</font> | |\n",
    "| 2 | 0 | 0 | 3 | <font color='red'>$Y_2$</font>$\\times$<font color='green'>$\\frac{4}{3}$</font> | |\n",
    "| 3 | 0 | 0 | 5 | <font color='red'>$Y_3$</font>$\\times$<font color='green'>$\\frac{4}{3}$</font> | |\n",
    "| 4 | 0 | 1 | 8 | | <font color='red'>$Y_4$</font>$\\times$<font color='green'>4</font> |\n",
    "| 5 | 1 | 0 | 2 | <font color='red'>$Y_5$</font>$\\times$<font color='green'>2</font> | |\n",
    "| 6 | 1 | 0 | 4 | <font color='red'>$Y_6$</font>$\\times$<font color='green'>2</font> | |\n",
    "| 7 | 1 | 1 | 8 | | <font color='red'>$Y_7$</font>$\\times$<font color='green'>2</font> |\n",
    "| 8 | 1 | 1 | 6 | | <font color='red'>$Y_8$</font>$\\times$<font color='green'>2</font> |\n",
    "\n",
    "\n",
    "Next, let's see how it does in our data example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x13b5bcf5a58>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "data_example2.plot.scatter(x=\"X\", y=\"Y\", c=\"A\", cmap=\"rainbow\", colorbar=False);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Estimated Association: 1.188 (0.367)\n",
      "Simulated ATE: 1.318\n"
     ]
    }
   ],
   "source": [
    "ctrl_grp = data_example2[data_example2.A == 0]\n",
    "trt_grp = data_example2[data_example2.A == 1]\n",
    "alpha = trt_grp.Y.mean() - ctrl_grp.Y.mean()\n",
    "alpha_err = 1.96 * np.sqrt(\n",
    "        trt_grp.Y.var() / trt_grp.shape[0] + \n",
    "        ctrl_grp.Y.var() / ctrl_grp.shape[0])\n",
    "print(\"Estimated Association: {:.3f}\".format(alpha), \"({:.3f})\".format(alpha_err))\n",
    "\n",
    "theta = data_example2.Y1.mean() - data_example2.Y0.mean()\n",
    "print(\"Simulated ATE: {:.3f}\".format(theta))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In practice, we never know $e(X_i)$'s and must use weights based on propensity scores estimated from logistic regression or modeling approaches instead\n",
    "\n",
    "We can estimate the propensity using the `CausalInference` package's methods `est_propensity_s` or `est_propensity`, which uses logistic regression on the covariate to estimate propensity:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Estimated ATE (by weighting based method): 1.195\n"
     ]
    }
   ],
   "source": [
    "cm.est_propensity_s()\n",
    "propensity = cm.propensity[\"fitted\"]\n",
    "\n",
    "data_example2[\"ipw\"] = np.where(\n",
    "    data_example2.A == 1, \n",
    "    1 / propensity,\n",
    "    1 / (1 - propensity))\n",
    "data_example2[\"wY\"] = data_example2.Y * data_example2.ipw\n",
    "\n",
    "psate = data_example2[data_example2.A == 1][\"wY\"].sum() / data_example2[data_example2.A == 1][\"ipw\"].sum() - data_example2[data_example2.A == 0][\"wY\"].sum() / data_example2[data_example2.A == 0][\"ipw\"].sum()\n",
    "\n",
    "print(\"Estimated ATE (by weighting based method): {:.3f}\".format(psate))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The inverse probability weights we used to estimate ATE is $w_i = \\frac{A_i}{e(X_i)} + \\frac{1 - A_i}{1 - e(X_i)}$, should we use this to estimate ATT and ATC?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Estimated ATC (by weighting based method): 0.930\n",
      "Estimated ATT (by weighting based method): 1.352\n"
     ]
    }
   ],
   "source": [
    "data_example2[\"cipw\"] = np.where(\n",
    "    data_example2.A == 1, \n",
    "    (1 - propensity) / propensity,\n",
    "    1)\n",
    "data_example2[\"cwY\"] = data_example2.Y * data_example2.cipw\n",
    "psatc = data_example2[data_example2.A == 1][\"cwY\"].sum() / data_example2[data_example2.A == 1][\"cipw\"].sum() - data_example2[data_example2.A == 0][\"cwY\"].sum() / data_example2[data_example2.A == 0][\"cipw\"].sum()\n",
    "print(\"Estimated ATC (by weighting based method): {:.3f}\".format(psatc))\n",
    "\n",
    "data_example2[\"tipw\"] = np.where(\n",
    "    data_example2.A == 1, \n",
    "    1,\n",
    "    propensity / (1 - propensity))\n",
    "data_example2[\"twY\"] = data_example2.Y * data_example2.tipw\n",
    "psatt = data_example2[data_example2.A == 1][\"twY\"].sum() / data_example2[data_example2.A == 1][\"tipw\"].sum() - data_example2[data_example2.A == 0][\"twY\"].sum() / data_example2[data_example2.A == 0][\"tipw\"].sum()\n",
    "print(\"Estimated ATT (by weighting based method): {:.3f}\".format(psatt))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This does well in our situation - b is very dependent on how good our estimate of the propensity score is - for the data generator we're using for this examplute the relationship can be described well by plain logistic regression."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "$$\\def \\bX {\\textbf {X}}$$\n",
    "$$\\def \\balpha {\\boldsymbol{\\alpha}}$$\n",
    "$$\\def \\bbeta {\\boldsymbol{\\beta}}$$\n",
    "# Doubly Robust Weighted Estimator\n",
    "\n",
    "In practice, it might be difficult to know either the true model for outcome, or the true model for the weights, one solutuon is  to combine the inverse propensity score weighting estimators and the linear estimator of effect size together to try and reduce the flaws in either model. \n",
    "\n",
    "Such a proposal is called the [doubly robust weighted estimator](https://academic.oup.com/aje/article/173/7/761/103691), or the augmented inverse propensity weighted (AIPW) estimator.\n",
    "\n",
    "Recall two estimators we have discussed:\n",
    "\n",
    "* Regression Based Estimator for ATE: \n",
    "    - When assumptions are satisfied, we can identify the regression of $Y$ on $A$ and $\\boldsymbol{X}$, e.g. for continuous outcome, $E(Y\\vert A, \\bX)=m(A, \\bX; \\balpha)=\\alpha_0 + \\alpha_a A + \\bX^T\\boldsymbol{\\alpha}_X$\n",
    "    - We can estimate the mean of counterfactual $E(Y^1)$ as ${N}^{-1}\\sum_{i=1}^N m(A_i=1, \\bX_i; \\hat\\balpha)$\n",
    "    - Similarly, we can estimate the mean of counterfactual $E(Y^0)$ as ${N}^{-1}\\sum_{i=1}^N m(A_i=0, \\bX_i; \\hat\\balpha)$\n",
    "    - ATE can then be estimated as the difference between these two quantities\n",
    "    - It requires that **the outcome model be correctly specified**\n",
    "    \n",
    "* Weighting Based Estimator for ATE:\n",
    "    - When assumptions are satisfied, we can estimate the propensity score from the regression of $A$ on $\\bX$, e.g. we postulate a logistic regression model \n",
    "    $P(A=1\\vert \\bX) = e(\\bX; \\bbeta) = \\frac{\\exp(\\beta_0 + \\bX^T\\bbeta_1)}{1 + exp(\\beta_0 + \\bX^T\\bbeta_1)}$\n",
    "    - We can estimate the mean of counterfactual $E(Y^1)$ as $N^{-1}\\sum_{i=1}^N (A_iY_i)/{e(\\bX_i, \\boldsymbol{\\hat\\beta})}$\n",
    "    - We can estimate the mean of counterfactual $E(Y^0)$ as $N^{-1}\\sum_{i=1}^N (1 - A_i)Y_i/[1 - e(\\bX_i, \\boldsymbol{\\hat\\beta})]$\n",
    "    - ATE can then be estimated as the difference between these two quantities\n",
    "    - It requires that **the propensity score model be correctly specified**\n",
    "\n",
    "The Doubly Robust Estimator combines these two proposals, and estimates ATE as \n",
    "\n",
    "\n",
    "$\\hat\\theta_{AIPW} = \\hat E(Y^1) - \\hat E(Y^0) = N^{-1}\\sum_{i=1}^N\\left[\\frac{A_iY_i}{e(\\bX_i, \\boldsymbol{\\hat\\beta})} - \\frac{A_i - e(\\bX_i, \\boldsymbol{\\hat\\beta})}{e(\\bX_i, \\boldsymbol{\\hat\\beta})}m(A_i=1, \\bX_i, {\\hat\\balpha}) \\right]\n",
    "    - N^{-1}\\sum_{i=1}^N\\left[\\frac{(1 - A_i)Y_i}{1 - e(\\bX_i, \\boldsymbol{\\hat\\beta})} + \\frac{A_i - e(\\bX_i, \\boldsymbol{\\hat\\beta})}{1 - e(\\bX_i, \\boldsymbol{\\hat\\beta})}m(A_i=0, \\bX_i, \\hat\\balpha) \\right]$\n",
    "\n",
    "\n",
    "Intuitively, if there is big bias in either $m(A_i, \\bX_i, \\hat\\balpha)$ or $e(\\bX_i, \\boldsymbol{\\hat\\beta})$, there is an additional term in this new estimator that takes into account the other model. \n",
    "\n",
    "It can be shown that if\n",
    "* The regression model is incorrect but the propensity model is correct\n",
    "    \n",
    "    OR\n",
    "* The propensity model is incorrect but the regression model is correct\n",
    "    \n",
    "    then $\\hat\\theta_{AIPW}$ is a (consistent) estimator for the ATE.\n",
    "\n",
    "We can apply this estimator in our simulation study:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: Weighting\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      1.410      0.179      7.864      0.000      1.059      1.762\n",
      "\n"
     ]
    }
   ],
   "source": [
    "cm = CausalModel(\n",
    "    Y=data_example2.Y.values, \n",
    "    D=data_example2.A.values, \n",
    "    X=data_example2.X.values)\n",
    "\n",
    "cm.est_propensity_s()\n",
    "cm.est_via_weighting()\n",
    "\n",
    "print(cm.estimates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Some Practical Issues \n",
    "\n",
    "The causal inference tools we discussed so far require the assumptions. Yet, in practice, these assumptions can never be tested. In this section, we will discuss some considerations regarding applying counterfactual modeling approaches in practice."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## About the Positivity Assumption\n",
    "\n",
    "When there are areas of covariate space which contains only the treated or untreated samples, i.e., there are some subgroup of patients who may hardly be assigned to one treatment arm, then the problem become difficult. We have to extrapolate the effect of the treatment - which will depend heavily on the additional assumptions we imposed on the model structure. \n",
    "\n",
    "We may look at the following example:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now for subject $i$ ($i=1,⋯,1000$), we generate\n",
    "\n",
    "* the confounder $X_i \\sim \\text{Uniform}(0,1)$;\n",
    "* binary treatment indicator $A \\sim \\text{Bernoulli}(p_{a,i})$, with \n",
    "\n",
    "$p_{a,i} = \\left\\{\n",
    "\\begin{array}{cc}\n",
    "0 & \\text{if }X_i<0.1\n",
    "\\\\\n",
    "X_i & \\text{if }0.1\\leq X_i \\leq 0.9\n",
    "\\\\\n",
    "1 & \\text{if }X_i > 0.9\n",
    "\\end{array}\n",
    "\\right.$\n",
    "* the (true) counterfactuals: \n",
    "    - $Y^0_i = -4(X_i - 0.3)\\times I(X_i\\geq 0.3) + \\epsilon_i$\n",
    "    - $Y^1_i = 1 - 4(X_i - 0.7)\\times I(X_i< 0.7) + \\epsilon_i$\n",
    "    - where $\\epsilon_i \\sim N(0,0.3^2)$\n",
    "* the observed outcome $Y_i = Y^1_i \\times A_i + Y^0_i \\times (1 - A_i)$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<matplotlib.lines.Line2D at 0x13b603006d8>]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x13b60300b38>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "\"\"\"\n",
    "Data Example 3\n",
    "  \n",
    "\"\"\"\n",
    "n_samples = 1000\n",
    "X = np.random.uniform(size=n_samples)\n",
    "p_a = np.where(X < 0.1, 0, np.where(X > 0.9, 1, X))\n",
    "A = np.random.binomial(n=1, p=p_a, size=n_samples)\n",
    "eY = 0.3 * np.random.normal(size=n_samples)\n",
    "Y0 = np.where(X >= 0.4, -4*(X - 0.4), 0) + eY\n",
    "Y1 = np.where(X < 0.6,  -4*(X - 0.6), 0) + 1 + eY\n",
    "Y = np.where(A == 0, Y0, Y1)\n",
    "data_example3 = pd.DataFrame({\"X\":X, \"A\":A, \"Y\":Y, \"Y0\":Y0, \"Y1\":Y1})\n",
    "\n",
    "data_example3.plot.scatter(x=\"X\", y=\"Y\", c=\"A\", cmap=\"rainbow\", colorbar=False)\n",
    "# latent traj\n",
    "t = np.linspace(0,1,100)\n",
    "y0 =  np.where(t >= 0.4, -4*(t - 0.4), 0)\n",
    "y1 =  np.where(t < 0.6,  -4*(t - 0.6), 0) + 1\n",
    "plt.plot(t, y0, \"b\")\n",
    "plt.plot(t, y1, \"r\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Estimated Association: 1.516 (0.070)\n",
      "Simulated ATE: 2.432\n"
     ]
    }
   ],
   "source": [
    "ctrl_grp = data_example3[data_example3.A == 0]\n",
    "trt_grp = data_example3[data_example3.A == 1]\n",
    "alpha = trt_grp.Y.mean() - ctrl_grp.Y.mean()\n",
    "alpha_err = 1.96 * np.sqrt(\n",
    "        trt_grp.Y.var() / trt_grp.shape[0] + \n",
    "        ctrl_grp.Y.var() / ctrl_grp.shape[0])\n",
    "print(\"Estimated Association: {:.3f}\".format(alpha), \"({:.3f})\".format(alpha_err))\n",
    "\n",
    "theta = data_example3.Y1.mean() - data_example3.Y0.mean()\n",
    "print(\"Simulated ATE: {:.3f}\".format(theta))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: OLS\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      2.183      0.037     59.455      0.000      2.111      2.255\n",
      "           ATC      2.158      0.045     48.236      0.000      2.070      2.245\n",
      "           ATT      2.208      0.041     53.322      0.000      2.127      2.289\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# OLS estimator\n",
    "cm = CausalModel(\n",
    "    Y=data_example3.Y.values, \n",
    "    D=data_example3.A.values, \n",
    "    X=data_example3.X.values)\n",
    "\n",
    "cm.est_via_ols()\n",
    "\n",
    "print(cm.estimates)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: OLS\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      2.183      0.037     59.455      0.000      2.111      2.255\n",
      "           ATC      2.158      0.045     48.236      0.000      2.070      2.245\n",
      "           ATT      2.208      0.041     53.322      0.000      2.127      2.289\n",
      "\n",
      "Treatment Effect Estimates: Matching\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      2.502      0.118     21.150      0.000      2.270      2.734\n",
      "           ATC      2.418      0.183     13.221      0.000      2.059      2.776\n",
      "           ATT      2.585      0.138     18.667      0.000      2.313      2.856\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Matching estimator\n",
    "cm.est_via_matching()\n",
    "print(cm.estimates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Trimming\n",
    "\n",
    "A simple solution is to only make predictions for the counterfactual in regions where there is a good overlap, or \"trim\" points where there is not good overlap. For high dimensional data \"good overlap\" can be difficult to define - using just the propensity score to define overlap is one way to solve this. \n",
    "\n",
    "`CausalInference` offers a method to trim the data based on the propensity score"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: Matching\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      2.346      0.062     37.814      0.000      2.224      2.468\n",
      "           ATC      2.311      0.078     29.460      0.000      2.158      2.465\n",
      "           ATT      2.379      0.074     32.121      0.000      2.234      2.524\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# trimming\n",
    "cm2 = CausalModel(\n",
    "    Y=data_example3.Y.values, \n",
    "    D=data_example3.A.values, \n",
    "    X=data_example3.X.values)\n",
    "\n",
    "cm2.est_propensity_s()\n",
    "cm2.trim_s()\n",
    "cm2.est_via_matching()\n",
    "\n",
    "print(cm2.estimates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can look at what is going on here"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Simulated ATE: 2.252\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x13b5f65ada0>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# mask out the trimmed portion\n",
    "propensity = cm2.propensity[\"fitted\"]\n",
    "cutoff = cm2.cutoff\n",
    "mask = (propensity > cutoff) &  (propensity < 1 - cutoff)\n",
    "\n",
    "# plot the data\n",
    "data_example3[mask].plot.scatter(x=\"X\", y=\"Y\", c=\"A\", cmap=\"rainbow\", colorbar=False)\n",
    "\n",
    "# latent traj\n",
    "t = np.linspace(0,1,100)\n",
    "y0 =  np.where(t >= 0.4, -4*(t - 0.4), 0)\n",
    "y1 =  np.where(t < 0.6,  -4*(t - 0.6), 0) + 1\n",
    "plt.plot(t, y0, \"b\")\n",
    "plt.plot(t, y1, \"r\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Basically, what it does is to focus on some subgroup of patients, where the overlapping (between the two treatmeant groups) is better. For the samples left out, we cannot make any causal conclusion due to the violation of the positivity assumption."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Stratification\n",
    "\n",
    "Another propensity score based method is stratification (or blocking). It consist of grouping the data points into strata with similar propensity (very similar idea as matching)\n",
    "\n",
    "We can use the `stratify` (need to provide boundaries) or `stratify_s` (automatically choose the boundaries) methods to determine the strata, and then use `est_via_blocking` method to combine the estimates of different strata to estimate ATE for the entire population:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Treatment Effect Estimates: Blocking\n",
      "\n",
      "                     Est.       S.e.          z      P>|z|      [95% Conf. int.]\n",
      "--------------------------------------------------------------------------------\n",
      "           ATE      2.477      0.037     66.684      0.000      2.404      2.550\n",
      "           ATC      2.404      0.064     37.804      0.000      2.280      2.529\n",
      "           ATT      2.549      0.027     94.766      0.000      2.496      2.601\n",
      "\n"
     ]
    }
   ],
   "source": [
    "cm = CausalModel(\n",
    "    Y=data_example3.Y.values, \n",
    "    D=data_example3.A.values, \n",
    "    X=data_example3.X.values)\n",
    "\n",
    "cm.est_propensity_s()\n",
    "cm.stratify_s()\n",
    "cm.est_via_blocking()\n",
    "print(cm.estimates)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can look at the strata"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Stratification Summary\n",
      "\n",
      "              Propensity Score         Sample Size     Ave. Propensity   Outcome\n",
      "   Stratum      Min.      Max.  Controls   Treated  Controls   Treated  Raw-diff\n",
      "--------------------------------------------------------------------------------\n",
      "         1     0.044     0.093       122         4     0.066     0.090     2.940\n",
      "         2     0.094     0.176       101        24     0.129     0.138     2.621\n",
      "         3     0.177     0.342        92        33     0.256     0.268     2.088\n",
      "         4     0.342     0.511        70        55     0.424     0.435     1.814\n",
      "         5     0.514     0.821        89       161     0.671     0.685     1.999\n",
      "         6     0.821     0.864        14        49     0.840     0.847     2.633\n",
      "         7     0.865     0.900         6        56     0.880     0.883     2.744\n",
      "         8     0.900     0.951         2       122     0.905     0.930     3.499\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(cm.strata)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Stratify the data into groups by propensity score is useful when we don't have any prior knowledge of what constitutes \"similar\" units. However if you have prior knowledge the different groups of your samples are likely to be affected by the intervention in similar ways, it is recommended to work on these predefined subgroups and then calculate the overall ATE if needed."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.4"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}