notebooks/assortment-optimization.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Importing the right base libraries\n",
    "import os\n",
    "# Remove GPU use\n",
    "os.environ[\"CUDA_VISIBLE_DEVICES\"] = \"\"\n",
    "\n",
    "import sys\n",
    "sys.path.append(\"../../\")\n",
    "\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>TRANSACTION_DT</th>\n",
       "      <th>CUSTOMER_ID</th>\n",
       "      <th>AGE_GROUP</th>\n",
       "      <th>PIN_CODE</th>\n",
       "      <th>PRODUCT_SUBCLASS</th>\n",
       "      <th>PRODUCT_ID</th>\n",
       "      <th>AMOUNT</th>\n",
       "      <th>ASSET</th>\n",
       "      <th>SALES_PRICE</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>1104905</td>\n",
       "      <td>45-49</td>\n",
       "      <td>115</td>\n",
       "      <td>110411</td>\n",
       "      <td>4710199010372</td>\n",
       "      <td>2</td>\n",
       "      <td>24</td>\n",
       "      <td>30</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>418683</td>\n",
       "      <td>45-49</td>\n",
       "      <td>115</td>\n",
       "      <td>120107</td>\n",
       "      <td>4710857472535</td>\n",
       "      <td>1</td>\n",
       "      <td>48</td>\n",
       "      <td>46</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>1057331</td>\n",
       "      <td>35-39</td>\n",
       "      <td>115</td>\n",
       "      <td>100407</td>\n",
       "      <td>4710043654103</td>\n",
       "      <td>2</td>\n",
       "      <td>142</td>\n",
       "      <td>166</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>1849332</td>\n",
       "      <td>45-49</td>\n",
       "      <td>Others</td>\n",
       "      <td>120108</td>\n",
       "      <td>4710126092129</td>\n",
       "      <td>1</td>\n",
       "      <td>32</td>\n",
       "      <td>38</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>1981995</td>\n",
       "      <td>50-54</td>\n",
       "      <td>115</td>\n",
       "      <td>100205</td>\n",
       "      <td>4710176021445</td>\n",
       "      <td>1</td>\n",
       "      <td>14</td>\n",
       "      <td>18</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  TRANSACTION_DT  CUSTOMER_ID AGE_GROUP PIN_CODE  PRODUCT_SUBCLASS  \\\n",
       "0      11/1/2000      1104905     45-49      115            110411   \n",
       "1      11/1/2000       418683     45-49      115            120107   \n",
       "2      11/1/2000      1057331     35-39      115            100407   \n",
       "3      11/1/2000      1849332     45-49   Others            120108   \n",
       "4      11/1/2000      1981995     50-54      115            100205   \n",
       "\n",
       "      PRODUCT_ID  AMOUNT  ASSET  SALES_PRICE  \n",
       "0  4710199010372       2     24           30  \n",
       "1  4710857472535       1     48           46  \n",
       "2  4710043654103       2    142          166  \n",
       "3  4710126092129       1     32           38  \n",
       "4  4710176021445       1     14           18  "
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from choice_learn.datasets import load_tafeng\n",
    "\n",
    "tafeng_df = load_tafeng(as_frame=True)\n",
    "tafeng_df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>TRANSACTION_DT</th>\n",
       "      <th>CUSTOMER_ID</th>\n",
       "      <th>AGE_GROUP</th>\n",
       "      <th>PIN_CODE</th>\n",
       "      <th>PRODUCT_SUBCLASS</th>\n",
       "      <th>PRODUCT_ID</th>\n",
       "      <th>AMOUNT</th>\n",
       "      <th>ASSET</th>\n",
       "      <th>SALES_PRICE</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>1187366</td>\n",
       "      <td>25-29</td>\n",
       "      <td>221</td>\n",
       "      <td>130315</td>\n",
       "      <td>4714981010038</td>\n",
       "      <td>2</td>\n",
       "      <td>56</td>\n",
       "      <td>48</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>630849</td>\n",
       "      <td>40-44</td>\n",
       "      <td>115</td>\n",
       "      <td>130315</td>\n",
       "      <td>4714981010038</td>\n",
       "      <td>2</td>\n",
       "      <td>56</td>\n",
       "      <td>48</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>217361</td>\n",
       "      <td>45-49</td>\n",
       "      <td>115</td>\n",
       "      <td>120103</td>\n",
       "      <td>4710011401128</td>\n",
       "      <td>2</td>\n",
       "      <td>46</td>\n",
       "      <td>56</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>305167</td>\n",
       "      <td>&gt;65</td>\n",
       "      <td>115</td>\n",
       "      <td>110217</td>\n",
       "      <td>4719090900058</td>\n",
       "      <td>1</td>\n",
       "      <td>145</td>\n",
       "      <td>149</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>11/1/2000</td>\n",
       "      <td>760225</td>\n",
       "      <td>30-34</td>\n",
       "      <td>115</td>\n",
       "      <td>110106</td>\n",
       "      <td>4711271000014</td>\n",
       "      <td>1</td>\n",
       "      <td>14</td>\n",
       "      <td>16</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  TRANSACTION_DT  CUSTOMER_ID AGE_GROUP PIN_CODE  PRODUCT_SUBCLASS  \\\n",
       "0      11/1/2000      1187366     25-29      221            130315   \n",
       "1      11/1/2000       630849     40-44      115            130315   \n",
       "2      11/1/2000       217361     45-49      115            120103   \n",
       "3      11/1/2000       305167       >65      115            110217   \n",
       "4      11/1/2000       760225     30-34      115            110106   \n",
       "\n",
       "      PRODUCT_ID  AMOUNT  ASSET  SALES_PRICE  \n",
       "0  4714981010038       2     56           48  \n",
       "1  4714981010038       2     56           48  \n",
       "2  4710011401128       2     46           56  \n",
       "3  4719090900058       1    145          149  \n",
       "4  4711271000014       1     14           16  "
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tafeng_df = tafeng_df.loc[tafeng_df.PRODUCT_ID.isin(tafeng_df.PRODUCT_ID.value_counts().index[:20])].reset_index(drop=True)\n",
    "tafeng_df = tafeng_df.loc[tafeng_df.AGE_GROUP.isin(['25-29', '40-44', '45-49', '>65', '30-34', '35-39', '50-54',\n",
    "       '55-59', '60-64'])].reset_index(drop=True)\n",
    "tafeng_df.head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "tafeng_df[\"twenties\"] = tafeng_df.apply(lambda row: 1 if row[\"AGE_GROUP\"] == \"25-29\" else 0, axis=1)\n",
    "tafeng_df[\"thirties\"] = tafeng_df.apply(lambda row: 1 if row[\"AGE_GROUP\"] in ([\"30-34\", \"35-39\"]) else 0, axis=1)\n",
    "tafeng_df[\"forties\"] = tafeng_df.apply(lambda row: 1 if row[\"AGE_GROUP\"] in ([\"40-44\", \"45-49\"]) else 0, axis=1)\n",
    "tafeng_df[\"fifties\"] = tafeng_df.apply(lambda row: 1 if row[\"AGE_GROUP\"] in ([\"50-54\", \"55-59\"]) else 0, axis=1)\n",
    "tafeng_df[\"sixties_and_above\"] = tafeng_df.apply(lambda row: 1 if row[\"AGE_GROUP\"] in ([\"60-64\", \">65\"]) else 0, axis=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# product ID to index\n",
    "id_to_index = {}\n",
    "for i, product_id in enumerate(np.sort(tafeng_df.PRODUCT_ID.unique())):\n",
    "    id_to_index[product_id] = i\n",
    "\n",
    "prices = [[0] for _ in range(len(id_to_index))]\n",
    "for k, v in id_to_index.items():\n",
    "    prices[v][0] = tafeng_df.loc[tafeng_df.PRODUCT_ID == k].SALES_PRICE.to_numpy()[0]\n",
    "\n",
    "# Create the arrays that will constitute the ChoiceDataset\n",
    "\n",
    "shared_features = []\n",
    "items_features = []\n",
    "choices = []\n",
    "\n",
    "for i, row in tafeng_df.iterrows():\n",
    "    item_index = id_to_index[row.PRODUCT_ID]\n",
    "    prices[item_index][0] = row.SALES_PRICE\n",
    "    shared_features.append(row[['twenties', 'thirties', 'forties', 'fifties', 'sixties_and_above']].to_numpy())\n",
    "    items_features.append(prices)\n",
    "    choices.append(item_index)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "from choice_learn.data import ChoiceDataset\n",
    "\n",
    "dataset = ChoiceDataset(\n",
    "    shared_features_by_choice=shared_features,\n",
    "    shared_features_by_choice_names=['twenties', 'thirties', 'forties', 'fifties', 'sixties_and_above>'],\n",
    "    items_features_by_choice=items_features,\n",
    "    items_features_by_choice_names=[\"SALES_PRICE\"],\n",
    "    choices=choices\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2024-10-02 09:55:06.720384: I external/local_tsl/tsl/cuda/cudart_stub.cc:32] Could not find cuda drivers on your machine, GPU will not be used.\n",
      "2024-10-02 09:55:06.722824: I external/local_tsl/tsl/cuda/cudart_stub.cc:32] Could not find cuda drivers on your machine, GPU will not be used.\n",
      "2024-10-02 09:55:06.749567: I tensorflow/core/platform/cpu_feature_guard.cc:210] This TensorFlow binary is optimized to use available CPU instructions in performance-critical operations.\n",
      "To enable the following instructions: AVX2 FMA, in other operations, rebuild TensorFlow with the appropriate compiler flags.\n",
      "2024-10-02 09:55:07.334247: W tensorflow/compiler/tf2tensorrt/utils/py_utils.cc:38] TF-TRT Warning: Could not find TensorRT\n",
      "2024-10-02 09:55:07.728920: E external/local_xla/xla/stream_executor/cuda/cuda_driver.cc:282] failed call to cuInit: CUDA_ERROR_NO_DEVICE: no CUDA-capable device is detected\n",
      "2024-10-02 09:55:07.728951: I external/local_xla/xla/stream_executor/cuda/cuda_diagnostics.cc:134] retrieving CUDA diagnostic information for host: research-Lambda-Vector\n",
      "2024-10-02 09:55:07.728954: I external/local_xla/xla/stream_executor/cuda/cuda_diagnostics.cc:141] hostname: research-Lambda-Vector\n",
      "2024-10-02 09:55:07.729025: I external/local_xla/xla/stream_executor/cuda/cuda_diagnostics.cc:165] libcuda reported version is: 525.116.4\n",
      "2024-10-02 09:55:07.729037: I external/local_xla/xla/stream_executor/cuda/cuda_diagnostics.cc:169] kernel reported version is: 525.116.4\n",
      "2024-10-02 09:55:07.729040: I external/local_xla/xla/stream_executor/cuda/cuda_diagnostics.cc:248] kernel version seems to match DSO: 525.116.4\n",
      "100%|██████████| 300/300 [02:07<00:00,  2.35it/s]\n"
     ]
    }
   ],
   "source": [
    "from choice_learn.models import ConditionalLogit\n",
    "\n",
    "model = ConditionalLogit(optimizer=\"Adam\", batch_size=1024, epochs=300, lr=0.002)\n",
    "\n",
    "for age_category in ['twenties', 'thirties', 'forties', 'fifties', 'sixties_and_above>']:\n",
    "    model.add_coefficients(coefficient_name=age_category,\n",
    "    feature_name=age_category,\n",
    "    items_indexes=list(range(20)))\n",
    "\n",
    "model.add_shared_coefficient(coefficient_name=\"price\", feature_name=\"SALES_PRICE\", items_indexes=list(range(20)))\n",
    "\n",
    "hist = model.fit(dataset)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Text(0, 0.5, 'Negative Log Likelihood')"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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N98UBEEQvv32W8HNzU0oLS0VX9+8ebMglUqFnJwcQRAEwdfXV5g5c2atdQAgfPDBB+Lz0tJSQSKRCL/99pvZ9pOILIdjkojooTFgwADExcUZLHN3dxd/Dg8PN3gtPDwcR48eBQCcOXMG3bt3h6Ojo/h6ZGQk9Ho9zp07B4lEguvXr+Pxxx+/bx26desm/uzo6AhnZ2fk5ubWd5eIyIoYkojooeHo6Fij++tBJBIJAEAQBPFnY2VUKlWdtieXy2usq9frTaoTEdkGjkkioiYjJSWlxvOOHTsCADp37oyjR4+irKxMfH3fvn2QSqVo3749nJ2d0bp1a/zxxx8WrTMRWQ9bkojooaHRaJCTk2OwzM7ODh4eHgCAn376CT179kSfPn0QHx+PQ4cOYfny5QCAF198ER999BEmTJiA2bNnIy8vD1OmTMG4cePg5eUFAJg9ezYmT54MT09PDB06FCUlJdi3bx+mTJli2R0lIotgSCKih8bWrVvh4+NjsKxDhw44e/YsgKorz9atW4d//OMf8Pb2Rnx8PDp37gwAcHBwwLZt2/DWW28hNDQUDg4OGDVqFBYsWCBua8KECSgvL8fChQvx7rvvwsPDA88995zldpCILEoiCIJg7UoQETU0iUSC9evXY+TIkdauChE1EhyTRERERGQEQxIRERGRERyTRERNAkcWEJGp2JJEREREZARDEhEREZERDElERERERjAkERERERnBkERERERkBEMSERERkREMSURERERGMCQRERERGfH/AT1sZxVrIg1LAAAAAElFTkSuQmCC",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "plt.plot(hist[\"train_loss\"])\n",
    "plt.xlabel(\"Epoch\")\n",
    "plt.ylabel(\"Negative Log Likelihood\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "future_prices = np.stack([items_features[-1]]*5, axis=0)\n",
    "age_category = np.eye(5).astype(\"float32\")\n",
    "predicted_utilities = model.compute_batch_utility(shared_features_by_choice=age_category,\n",
    "                                                  items_features_by_choice=future_prices,\n",
    "                                                  available_items_by_choice=np.ones((5, 20)),\n",
    "                                                  choices=None\n",
    "                                                  )\n",
    "\n",
    "age_category_weights = np.sum(shared_features, axis=0) / len(shared_features)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "from choice_learn.toolbox.assortment_optimizer import LatentClassAssortmentOptimizer\n",
    "\n",
    "opt = LatentClassAssortmentOptimizer(\n",
    "    solver=\"or-tools\", # Solver to use, either \"or-tools\" or \"gurobi\"\n",
    "    class_weights=age_category_weights, # Weights of each class\n",
    "    class_utilities=np.exp(predicted_utilities), # utilities in the shape (n_classes, n_items)\n",
    "    itemwise_values=future_prices[0][:, 0], # Values to optimize for each item, here price that is used to compute turnover\n",
    "    assortment_size=12) # Size of the assortment we want\n",
    "\n",
    "assortment, opt_obj = opt.solve()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Our Optimal Assortment is:\n",
      "[0. 0. 1. 0. 0. 0. 0. 1. 1. 0. 0. 0. 1. 0. 0. 0. 0. 0. 1. 1.]\n",
      "With an estimated average revenue of: 135.35206572413668\n",
      "Size of our assortment: 6 which is fine with our limit of 12!\n"
     ]
    }
   ],
   "source": [
    "print(\"Our Optimal Assortment is:\")\n",
    "print(assortment)\n",
    "print(\"With an estimated average revenue of:\", opt_obj)\n",
    "print(\"Size of our assortment:\", np.sum((assortment > 0)), \"which is fine with our limit of 12!\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "choice_learn",
   "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.11.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}