examples/synthetic-pscore.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quickstart: Use Cases and Examples with *Interpretable OPE Evaluator*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook demonstrates an example of conducting Interpretable Evaluation for Off-Policy Evaluation (IEOE). We use synthetic logged bandit feedback data generated using [`obp`](https://github.com/st-tech/zr-obp) and evaluate the performance of Direct Method (DM), Doubly Robust (DR), Doubly Robust with Shrinkage (DRos), and Inverse Probability Weighting (IPW).\n",
    "\n",
    "Our example contains the following three major steps:\n",
    "\n",
    "1. Data Preparation\n",
    "2. Setting Hyperparameter Spaces for Off-Policy Evaluation\n",
    "3. Interpretable Evaluation for Off-Policy Evaluation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from sklearn.linear_model import LogisticRegression\n",
    "from sklearn.ensemble import RandomForestClassifier as RandomForest\n",
    "\n",
    "# import necesarry functions from obp\n",
    "import obp\n",
    "from obp.dataset import (\n",
    "    SyntheticBanditDataset,\n",
    "    logistic_reward_function,\n",
    "    linear_behavior_policy\n",
    ")\n",
    "from obp.policy import IPWLearner\n",
    "from obp.ope import (\n",
    "    DirectMethod,\n",
    "    DoublyRobust,\n",
    "    DoublyRobustWithShrinkage,\n",
    "    InverseProbabilityWeighting,\n",
    ")\n",
    "\n",
    "# import interpretable ope evaluator from pyieoe\n",
    "from pyieoe.evaluator import InterpretableOPEEvaluator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'0.4.0'"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "obp.__version__"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Data Preparation\n",
    "\n",
    "In order to conduct IEOE using `pyieoe`, we need to prepare logged bandit feedback data, action distributions of evaluation policies, and ground truth policy values of evaluation policies. Because `pyieoe` is built with the intention of being used with `obp`, these inputs must follow the conventions in `obp`. Specifically, logged bandit feedback data must be of type `BanditFeedback`, action distributions must be of type `np.ndarray`, and ground truth policy values must be of type `float` (or `int`). \n",
    "\n",
    "In this example, we generate synthetic logged bandit feedback data and perform off-policy learning to obtain two sets of evaluation policies along with their action distributions and ground truth policy values using `obp`. For a detailed explanation of this process, please refer to the [official obp example](https://github.com/st-tech/zr-obp/blob/master/examples/quickstart/quickstart_synthetic.ipynb)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# generate a synthetic bandit dataset with 10 actions\n",
    "# we use `logistic function` as the reward function and `linear_behavior_policy` as the behavior policy.\n",
    "# one can define their own reward function and behavior policy such as nonlinear ones. \n",
    "dataset = SyntheticBanditDataset(\n",
    "    n_actions=10,\n",
    "    dim_context=5,\n",
    "    reward_type=\"binary\", # \"binary\" or \"continuous\"\n",
    "    reward_function=logistic_reward_function,\n",
    "    behavior_policy_function=linear_behavior_policy,\n",
    "    random_state=12345\n",
    ")\n",
    "# obtain training and test sets of synthetic logged bandit feedback\n",
    "n_rounds_train, n_rounds_test = 10000, 10000\n",
    "bandit_feedback_train = dataset.obtain_batch_bandit_feedback(n_rounds=n_rounds_train)\n",
    "bandit_feedback_test = dataset.obtain_batch_bandit_feedback(n_rounds=n_rounds_test)\n",
    "\n",
    "# define IPWLearner with Logistic Regression as its base ML model\n",
    "evaluation_policy_a = IPWLearner(\n",
    "    n_actions=dataset.n_actions,\n",
    "    len_list=dataset.len_list,\n",
    "    base_classifier=LogisticRegression(C=100, random_state=12345)\n",
    ")\n",
    "# train IPWLearner on the training set of the synthetic logged bandit feedback\n",
    "evaluation_policy_a.fit(\n",
    "    context=bandit_feedback_train[\"context\"],\n",
    "    action=bandit_feedback_train[\"action\"],\n",
    "    reward=bandit_feedback_train[\"reward\"],\n",
    "    pscore=bandit_feedback_train[\"pscore\"]\n",
    ")\n",
    "# obtains action choice probabilities for the test set of the synthetic logged bandit feedback\n",
    "action_dist_a = evaluation_policy_a.predict_proba(\n",
    "    context=bandit_feedback_test[\"context\"],\n",
    "    tau=0.1 # temperature hyperparameter\n",
    ")\n",
    "\n",
    "# define IPWLearner with Random Forest as its base ML model\n",
    "evaluation_policy_b = IPWLearner(\n",
    "    n_actions=dataset.n_actions,\n",
    "    len_list=dataset.len_list,\n",
    "    base_classifier=RandomForest(n_estimators=30, min_samples_leaf=10, random_state=12345)\n",
    ")\n",
    "# train IPWLearner on the training set of the synthetic logged bandit feedback\n",
    "evaluation_policy_b.fit(\n",
    "    context=bandit_feedback_train[\"context\"],\n",
    "    action=bandit_feedback_train[\"action\"],\n",
    "    reward=bandit_feedback_train[\"reward\"],\n",
    "    pscore=bandit_feedback_train[\"pscore\"]\n",
    ")\n",
    "# obtains action choice probabilities for the test set of the synthetic logged bandit feedback\n",
    "action_dist_b = evaluation_policy_b.predict_proba(\n",
    "    context=bandit_feedback_test[\"context\"],\n",
    "    tau=0.1 # temperature hyperparameter\n",
    ")\n",
    "\n",
    "# obtain ground truth policy value for each action choice probabilities\n",
    "expected_rewards = bandit_feedback_test[\"expected_reward\"]\n",
    "ground_truth_a = np.average(expected_rewards, weights=action_dist_a[:, :, 0], axis=1).mean()\n",
    "ground_truth_b = np.average(expected_rewards, weights=action_dist_b[:, :, 0], axis=1).mean()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Setting Hyperparameter Spaces for Off-Policy Evaluation\n",
    "\n",
    "An integral aspect of IEOE is the different sources of variance. The main sources of variance are evaluation policies, random states, hyperparameters of OPE estimators, and hyperparameters of regression models. \n",
    "\n",
    "In this step, we define the spaces from which the hyperparameters of OPE estimators / regression models are chosen. (The evaluation policy space is defined in the previous step, and the random state space will be defined in the next step.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set hyperparameter space for ope estimators\n",
    "\n",
    "# set hyperparameter space for the doubly robust with shrinkage estimator\n",
    "# with the following code, lambda_ will be chosen from a logarithm uniform distribution over the interval [0.001, 1000]\n",
    "lambda_ = {\n",
    "    \"lower\": 1e-3,\n",
    "    \"upper\": 1e3,\n",
    "    \"log\": True,\n",
    "    \"type\": float\n",
    "}\n",
    "dros_param = {\"lambda_\": lambda_}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# set hyperparameter space for regression models\n",
    "\n",
    "# set hyperparameter space for logistic regression\n",
    "# with the following code, C will be chosen from a logarithm uniform distribution over the interval [0.001, 100]\n",
    "C = {\n",
    "    \"lower\": 1e-3,\n",
    "    \"upper\": 1e2,\n",
    "    \"log\": True,\n",
    "    \"type\": float\n",
    "}\n",
    "# create a dictionary mapping hyperparamter names to hyperparamter spaces\n",
    "logistic_regression_param = {\"C\": C}\n",
    "\n",
    "# set hyperparameter space for the random forest classifier\n",
    "# with the following code, n_estimators will be chosen from a logarithm uniform distribution over the interval [50, 100]\n",
    "# the chosen value will be of type int\n",
    "n_estimators = {\n",
    "    \"lower\": 5e1,\n",
    "    \"upper\": 1e2,\n",
    "    \"log\": True,\n",
    "    \"type\": int\n",
    "}\n",
    "# with the following code, max_depth will be chosen from a uniform distribution over the interval [2, 10]\n",
    "# the chosen value will be of type int\n",
    "max_depth = {\n",
    "    \"lower\": 2,\n",
    "    \"upper\": 10,\n",
    "    \"log\": False,\n",
    "    \"type\": int\n",
    "}\n",
    "# with the following code, min_samples_split will be chosen from a uniform distribution over the interval [2, 10]\n",
    "# the chosen value will be of type int\n",
    "min_samples_split = {\n",
    "    \"lower\": 2,\n",
    "    \"upper\": 10,\n",
    "    \"log\": False,\n",
    "    \"type\": int\n",
    "}\n",
    "# create a dictionary mapping hyperparamter names to hyperparamter spaces\n",
    "random_forest_param = {\n",
    "    \"n_estimators\": n_estimators, \n",
    "    \"max_depth\": max_depth, \n",
    "    \"min_samples_split\": min_samples_split\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Interpretable Evaluation for Off-Policy Evaluation\n",
    "\n",
    "With the above steps completed, we can finally conduct IEOE by utilizing the `InterpretableOPEEvaluator` class.\n",
    "\n",
    "Here is a brief description for each parameter that can be passed into `InterpretableOPEEvaluator`:\n",
    "\n",
    "- `random_states`: a list of integers representing the random_state used when performing OPE; corresponds to the number of iterations\n",
    "- `bandit_feedback`: a list of logged bandit feedback data\n",
    "- `evaluation_policies`: a list of tuples representing (ground truth policy value, action distribution)\n",
    "- `ope_estimators`: a list of OPE ope_estimators\n",
    "- `ope_estimator_hyperparams`: a dictionary mapping OPE estimator names to OPE estimator hyperparameter spaces defined in step 2\n",
    "- `regression_models`: a list of regression_models\n",
    "- `regression_model_hyperparams`: a dictionary mapping regression models to regression model hyperparameter spaces defined in step 2"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# initializing class\n",
    "evaluator = InterpretableOPEEvaluator(\n",
    "    random_states=np.arange(1000),\n",
    "    bandit_feedbacks=[bandit_feedback_test],\n",
    "    evaluation_policies=[\n",
    "        (ground_truth_a, action_dist_a), \n",
    "        (ground_truth_b, action_dist_b)\n",
    "    ],\n",
    "    ope_estimators=[\n",
    "        DirectMethod(),\n",
    "        DoublyRobust(),\n",
    "        DoublyRobustWithShrinkage(),\n",
    "        InverseProbabilityWeighting(), \n",
    "    ],\n",
    "    ope_estimator_hyperparams={\n",
    "        DoublyRobustWithShrinkage.estimator_name: dros_param,\n",
    "    },\n",
    "    regression_models=[\n",
    "        LogisticRegression,\n",
    "        RandomForest\n",
    "    ],\n",
    "    regression_model_hyperparams={\n",
    "        LogisticRegression: logistic_regression_param,\n",
    "        RandomForest: random_forest_param\n",
    "    },\n",
    "    pscore_estimators=[\n",
    "        LogisticRegression,\n",
    "        RandomForest\n",
    "    ],\n",
    "    pscore_estimator_hyperparams={\n",
    "        LogisticRegression: logistic_regression_param,\n",
    "        RandomForest: random_forest_param\n",
    "    }\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can set the hyperparameters of OPE estimators / regression models after initializing `InterpretableOPEEvaluator` as well. Below is an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "# re-set hyperparameter space for the doubly robust with shrinkage estimator\n",
    "# with the following code, lambda_ will now be chosen from a logarithm uniform distribution over the interval [0.001, 100]\n",
    "evaluator.set_ope_estimator_hyperparam_space(\n",
    "    DoublyRobustWithShrinkage.estimator_name,\n",
    "    param_name=\"lambda_\",\n",
    "    lower=1e-3,\n",
    "    upper=1e2,\n",
    "    log=True,\n",
    "    type_=float,\n",
    ")\n",
    "\n",
    "# re-set hyperparameter space for logistic regression\n",
    "# with the following code, C will now be chosen from a logarithm uniform distribution over the interval [0.001, 100]\n",
    "evaluator.set_regression_model_hyperparam_space(\n",
    "    LogisticRegression,\n",
    "    param_name=\"C\",\n",
    "    lower=1e-2,\n",
    "    upper=1e2,\n",
    "    log=True,\n",
    "    type_=float,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once we have initialized `InterpretableOPEEvaluator`, we can call implemented methods to perform IEOE."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|██████████| 1000/1000 [22:37<00:00,  1.36s/it]\n"
     ]
    }
   ],
   "source": [
    "# estimate policy values\n",
    "# we obtain a dictionary mapping ope estimator names to np.ndarray storing the estimated policy value for each iteration\n",
    "policy_value = evaluator.estimate_policy_value()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dm: [0.61545221 0.62667349 0.62580662]\n",
      "dr: [0.63453571 0.64766526 0.64769435]\n",
      "dr-os: [0.61469144 0.62538813 0.62433734]\n",
      "ipw: [0.63682535 0.6131044  0.64696424]\n"
     ]
    }
   ],
   "source": [
    "print(\"dm:\", policy_value[\"dm\"][:3])\n",
    "print(\"dr:\", policy_value[\"dr\"][:3])\n",
    "print(\"dr-os:\", policy_value[\"dr-os\"][:3])\n",
    "print(\"ipw:\", policy_value[\"ipw\"][:3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# compute squared errors\n",
    "# we obtain a dictionary mapping ope estimator names to np.ndarray storing the calculated squared error for each iteration\n",
    "squared_error = evaluator.calculate_squared_error()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dm: [3.52705747e-04 5.06469838e-05 7.09983979e-05]\n",
      "dr: [9.18302903e-08 1.92518552e-04 1.81216579e-04]\n",
      "dr-os: [3.81860092e-04 7.05940719e-05 9.79177714e-05]\n",
      "ipw: [6.72196710e-06 4.27900436e-04 1.62092626e-04]\n"
     ]
    }
   ],
   "source": [
    "print(\"dm:\", squared_error[\"dm\"][:3])\n",
    "print(\"dr:\", squared_error[\"dr\"][:3])\n",
    "print(\"dr-os:\", squared_error[\"dr-os\"][:3])\n",
    "print(\"ipw:\", squared_error[\"ipw\"][:3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Figure size 432x288 with 0 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "image/png": "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H3/8MQoKCjBhwgRcddVVOHDggCq/xx57DDfeeCP27t2Lu+++u93fS9IJGOmStmzZwgCwf//7321eO2XKFHbHHXeo0v7617+yXr16OY5vueUWlpKSwiwWiyPtiiuuYMnJyayxsdGRds0117Bf//rX7cr72WefZVlZWa2W8ZprrmF33nmn43j69OnslltucbsOAFuxYgVjjDFZlll6ejp75ZVXHOdfffVVlpGRwWRZdpTvscceU+Vx/PhxBoDt2rXLY1lWr17NALCDBw860kpLS5nRaFTV1bnuFRUVDAD78ccfPeZ58uRJj+efffZZxnEcO378uFu68/fs2WefZQBYUVGRI+3gwYMMAFuzZo3H1zDG2Pr16xkAdvToUcYYYytWrGCe/mzccsstbPr06Y7jzMxM9uijj6quefDBB1mfPn0cx7169WJXX3216prLLruM/eY3v/H4PWCMsaVLl7KoqCh2/vx5R9rZs2eZ0Whky5cvd6Q5v8/exMXFsQ8++MDjOV/fw169erG//vWvqtfecccdbMqUKV7vK8syS0hIYB9//LGqvLfffrvqOl9+9jIyMtiTTz6puubXv/41EwTB6/2PHDnCOI5j+/fvV6U/99xzbMSIEa2W6YMPPmAA2Lp16xxpRUVFDAD73//+p7p21KhR7LbbbmOMMXb06FEGgD3//PNey0VCE7UkdFEsAPt6DR48WNXHmJaWhoEDB8JgMKjSSktLO3Sf+vp6PP744xg6dCiSkpIQExODb775BsePH29XPjzP46abblI1Ma9YsQI33ngjeN7+q7Ft2za8+eabjqbtmJgYDBkyBIC939uTwsJCmM1mDBgwwJGWkpKCgQMHei1LYmIi7rzzTsycOROXX3455s+fj4MHD/pUj9TUVPTs2bPN61JSUlTdCQMGDIDZbMa+fft8uo+vqqurcerUKUyePFmVPmXKFBw7dgz19fWONNcxL+np6Th37pzXvPft24chQ4bAbDY70lJTUzFw4MB21+ORRx5xdA3MmzdP1Urgz3vozdGjR/H73/8e/fr1Q1xcHOLi4lBVVeX28zp27FjVcVs/e9XV1Th9+rRbK9nEiRNbLc/27dvBGENOTo4q75deesntZ9q1TM3GjBnj+LqwsBAA3N7vyZMnu70n3vIjoYsGLnZR/fv3B8/zKCwsxLXXXtvqtTzPuwUVNpvN7TrX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\n",
      "text/plain": [
       "<Figure size 576x432 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# visualize cdf of squared errors for all ope estimators\n",
    "evaluator.visualize_cdf_aggregate(xmax=0.002)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dm': 0.00013605737809169543,\n",
       " 'dr': 0.00030526831334442775,\n",
       " 'dr-os': 0.00019635185243318376,\n",
       " 'ipw': 0.00020609207318572032}"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# compute the au-cdf score (area under cdf of squared error over interval [0, thershold]), higher score is better\n",
    "# we obtain a dictionary mapping ope estimator names to cvar scores \n",
    "au_cdf = evaluator.calculate_au_cdf_score(threshold=0.0004)\n",
    "au_cdf"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dm': 0.44569767690950873,\n",
       " 'dr': 1.0,\n",
       " 'dr-os': 0.6432107226656182,\n",
       " 'ipw': 0.6751178035081257}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# by activating the `scale` option, \n",
    "# we obtain the au_cdf scores where the highest score is scaled to 1\n",
    "au_cdf_scaled = evaluator.calculate_au_cdf_score(threshold=0.0004, scale=True)\n",
    "au_cdf_scaled"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dm': 0.000886828823044524,\n",
       " 'dr': 0.0003393236607679527,\n",
       " 'dr-os': 0.0008401878139005747,\n",
       " 'ipw': 0.004682647767546376}"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# compute the cvar score (expected value of squared error above probability alpha), lower score is better\n",
    "# we obtain a dictionary mapping ope estimator names to cvar scores \n",
    "cvar = evaluator.calculate_cvar_score(alpha=90)\n",
    "cvar"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dm': 2.6135189660439977,\n",
       " 'dr': 1.0,\n",
       " 'dr-os': 2.4760661016065693,\n",
       " 'ipw': 13.799944739923738}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# by activating the `scale` option, \n",
    "# we obtain the cvar scores where the lowest score is scaled to 1\n",
    "cvar_scaled = evaluator.calculate_cvar_score(alpha=90, scale=True)\n",
    "cvar_scaled"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}