02_Recommender_System_using_Multi_Armed_Bandit.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Product Recommender Using Multi-Armed Bandit Algorithms"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.748129Z",
     "start_time": "2019-07-15T05:03:24.262894Z"
    }
   },
   "outputs": [],
   "source": [
    "# Import packages\n",
    "import random\n",
    "import numpy as np\n",
    "import scipy.stats as stats\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.752754Z",
     "start_time": "2019-07-15T05:03:24.749358Z"
    }
   },
   "outputs": [],
   "source": [
    "class Bandit:\n",
    "    \"\"\"A useful class containing the multi-armed bandit and all its actions.\n",
    "\n",
    "    Attributes:\n",
    "        actions The actions that can be performed, numbered automatically 0, 1, 2...\n",
    "        payoff_probs    The underlying pay-off probabilities for each action.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, payoff_probs):\n",
    "        self.actions = range(len(payoff_probs))\n",
    "        self.payoff_probs = payoff_probs\n",
    "\n",
    "    def sample(self, action):\n",
    "        \n",
    "        \"\"\"Sample from the multi-armed by performing an action.\n",
    "\n",
    "        Args:\n",
    "            action (int): The action performed on the multi-armed bandit.\n",
    "        Returns:\n",
    "            int: It returns a reward based on that arm's pay-off probability.\n",
    "        \"\"\"\n",
    "    \n",
    "        selector = random.random()\n",
    "        # We are going to keep it simple with 1 or 0 being the only rewards\n",
    "        return 1 if selector <= self.payoff_probs[action] else 0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.761494Z",
     "start_time": "2019-07-15T05:03:24.753647Z"
    }
   },
   "outputs": [],
   "source": [
    "def random_agent(bandit, iterations):\n",
    "    \"\"\"Randomly select an action and reward.\"\"\"\n",
    "\n",
    "    for i in range(iterations):\n",
    "        a = random.choice(bandit.actions)\n",
    "        r = bandit.sample(a)\n",
    "        yield a, r"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.767559Z",
     "start_time": "2019-07-15T05:03:24.762613Z"
    }
   },
   "outputs": [],
   "source": [
    "def optimal_agent(bandit, iterations):\n",
    "    \"\"\"Select the best action by taking a sneak-peek at the bandit's probabilities.\"\"\"\n",
    "\n",
    "    for i in range(iterations):\n",
    "        a = bandit.payoff_probs.index(max(bandit.payoff_probs))\n",
    "        r = bandit.sample(a)\n",
    "        yield a, r"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.774424Z",
     "start_time": "2019-07-15T05:03:24.768767Z"
    }
   },
   "outputs": [],
   "source": [
    "def initial_explore_agent(bandit, iterations, initial_rounds=10):\n",
    "    \"\"\"\n",
    "    Initially explore initial_rounds times and then stick to the best action.\n",
    "    \"\"\"\n",
    "    pay_offs = dict()\n",
    "    best_action = -1\n",
    "    \n",
    "    for i in range(iterations):\n",
    "        # for the initial rounds pick a random action\n",
    "        if i < initial_rounds:\n",
    "            a = random.choice(bandit.actions)\n",
    "            r = bandit.sample(a)\n",
    "            \n",
    "            # Update rewards\n",
    "            if a in pay_offs:\n",
    "                pay_offs[a].append(r)\n",
    "            else:\n",
    "                pay_offs[a] = [r]\n",
    "        # otherwise pick the best one thus far\n",
    "        else:\n",
    "            if (best_action == -1):\n",
    "                # check for the action with the best average payoff\n",
    "                mean_dict = {}\n",
    "                for key, val in pay_offs.items():\n",
    "                    mean_dict[key] = np.mean(val)\n",
    "                best_action = max(mean_dict, key=mean_dict.get)\n",
    "            a = best_action\n",
    "            r = bandit.sample(a)\n",
    "        yield a, r"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Epsilon Greedy\n",
    "\n",
    "The epsilon greedy algorithm allow you to only explore random actions with epsilon probability. Otherwise, with the probability of 1-epsilon, you pick the action with the best average payoff.\n",
    "\n",
    "The reasoning behind this approach is that for a portion of the time the algorithm randomly explores the available actions, but it still exploits the best action the majority of the time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.782820Z",
     "start_time": "2019-07-15T05:03:24.777323Z"
    }
   },
   "outputs": [],
   "source": [
    "def epsilon_greedy_agent(\n",
    "        bandit,\n",
    "        iteractions,\n",
    "        epsilon=0.2,\n",
    "        initial_rounds=1,\n",
    "):\n",
    "    \"\"\"\n",
    "    Use the epsilon-greedy algorithm by performing the actioon with the bset average payoff with the probability(1-epsilon), otherwise pick a random action to keep exploring.\n",
    "\n",
    "    \"\"\"\n",
    "\n",
    "    pay_offs = dict()\n",
    "    for i in range(iteractions):\n",
    "        # Sometimes randomly pick an action to explore\n",
    "        if random.random() < epsilon or i < initial_rounds:\n",
    "            a = random.choice(bandit.actions)\n",
    "\n",
    "        # otherwise pick the best one thus far\n",
    "        else:\n",
    "            new_dict = {}\n",
    "            for key, val in pay_offs.items():\n",
    "                new_dict[key] = np.mean(val)\n",
    "            a = max(new_dict, key=new_dict.get)\n",
    "        r = bandit.sample(a)\n",
    "\n",
    "        # Update rewards\n",
    "        if a in pay_offs:\n",
    "            pay_offs[a].append(r)\n",
    "        else:\n",
    "            pay_offs[a] = [r]\n",
    "\n",
    "        yield a, r"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:24.789617Z",
     "start_time": "2019-07-15T05:03:24.784496Z"
    }
   },
   "outputs": [],
   "source": [
    "def decaying_epsilon_greedy_agent(bandit,\n",
    "                         iteractions,\n",
    "                         epsilon=0.2,\n",
    "                         initial_rounds=1,\n",
    "                         decay=0.99):\n",
    "    \"\"\"\n",
    "    Use the decaying epsilon-greedy algorithm by performing the actioon with the bset average payoff with the probability(1-epsilon), otherwise pick a random action to keep exploring.\n",
    "    \n",
    "    \"\"\"\n",
    "\n",
    "    pay_offs = dict()\n",
    "    for i in range(iteractions):\n",
    "        # Sometimes randomly pick an action to explore\n",
    "        if random.random() < epsilon or i < initial_rounds:\n",
    "            a = random.choice(bandit.actions)\n",
    "\n",
    "        # otherwise pick the best one thus far\n",
    "        else:\n",
    "            new_dict = {}\n",
    "            for key, val in pay_offs.items():\n",
    "                new_dict[key] = np.mean(val)\n",
    "            a = max(new_dict, key=new_dict.get)\n",
    "        r = bandit.sample(a)\n",
    "\n",
    "        # Update rewards\n",
    "        if a in pay_offs:\n",
    "            pay_offs[a].append(r)\n",
    "        else:\n",
    "            pay_offs[a] = [r]\n",
    "\n",
    "        epsilon *= decay\n",
    "\n",
    "        yield a, r"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2019-07-15T05:03:58.621067Z",
     "start_time": "2019-07-15T05:03:24.791128Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "random_agent : 48.795\n",
      "initial_explore_agent : 65.159\n",
      "epsilon_greedy_agent : 74.698\n",
      "decaying_epsilon_greedy_agent : 73.715\n",
      "optimal_agent : 100.301\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "def main():\n",
    "    random.seed(200) #used for reproducibility\n",
    "\n",
    "    pay_offs = [0.25, 0.3, 0.5, 0.1, 0.3, 0.25, 0]\n",
    "    bandit = Bandit(pay_offs)\n",
    "\n",
    "    f = plt.figure()\n",
    "    \n",
    "    methods = [random_agent, initial_explore_agent, epsilon_greedy_agent, decaying_epsilon_greedy_agent, optimal_agent]\n",
    "\n",
    "    number_of_iterations = 200\n",
    "    number_of_trials = 1000\n",
    "\n",
    "    for m in range(len(methods)):\n",
    "        method = methods[m]\n",
    "        total_rewards = []\n",
    "\n",
    "        list_of_cumulative_rewards = []\n",
    "        fan = []\n",
    "\n",
    "        for trial in range(number_of_trials):\n",
    "            total_reward = 0\n",
    "            cumulative_reward = []\n",
    "\n",
    "            for a, r in method(bandit, number_of_iterations):\n",
    "                total_reward += r\n",
    "                cumulative_reward.append(total_reward)\n",
    "\n",
    "\n",
    "            #plt.plot(cumulative_reward, alpha=.02, color=colors[m])\n",
    "            total_rewards.append(total_reward)\n",
    "\n",
    "            if trial == 0:\n",
    "                fan = pd.DataFrame(cumulative_reward, columns=['y'])\n",
    "                fan['x'] = fan.index+1\n",
    "            else:\n",
    "                fan2 = pd.DataFrame(cumulative_reward, columns=['y'])\n",
    "                fan2['x'] = fan2.index+1\n",
    "\n",
    "                fan = fan.append(fan2, ignore_index=True)\n",
    "\n",
    "            list_of_cumulative_rewards.append(cumulative_reward)\n",
    "\n",
    "        sns.lineplot(x='x', y='y', data=fan)  #default is to use bootstrap to calculate confidence interval     \n",
    "        \n",
    "        print(method.__name__, \":\", np.mean(total_rewards))\n",
    "\n",
    "    plt.title(\"Cumulative reward for each algorithm over {} iterations with {} trials.\".format(number_of_iterations, number_of_trials))\n",
    "    plt.ylabel(\"Cumulative reward\")\n",
    "    plt.xlabel(\"Iterations\")\n",
    "    plt.legend([method.__name__ for method in methods])\n",
    "    \n",
    "    f.savefig(\"./tmp/Iterations.pdf\", bbox_inches='tight')\n",
    "    f.savefig(\"./tmp/Iterations.svg\", bbox_inches='tight')\n",
    "\n",
    "    plt.show()\n",
    "\n",
    "if __name__ == \"__main__\":\n",
    "    main()\n"
   ]
  }
 ],
 "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.8"
  },
  "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
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}