tutorials/post_estimation_demos.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial: Post-Estimations\n",
    "\n",
    "**Author: Tianyu Du (tianyudu@stanford.edu)**\n",
    "\n",
    "This tutorial covers the toolkit in `torch-choice` for visualizing and analyzing models after model estimation.\n",
    "\n",
    "**Note**: models demonstrated in this tutorial are for demonstration purpose only, hence we don't estimate them in this tutorial. Instead, this tutorial focuses on APIs to visualize and analyze models."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import required dependencies.\n",
    "from time import time\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "import torch\n",
    "import torch.nn.functional as F\n",
    "\n",
    "from torch_choice.data import ChoiceDataset, JointDataset, utils\n",
    "from torch_choice.model import ConditionalLogitModel, NestedLogitModel\n",
    "from torch_choice.utils.run_helper import run"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# let's get a helper\n",
    "def print_dict_shape(d):\n",
    "    for key, val in d.items():\n",
    "        if torch.is_tensor(val):\n",
    "            print(f'dict.{key}.shape={val.shape}')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating  `ChoiceDataset` Object\n",
    "\n",
    "We first create a dummy `ChoiceDataset` object, please refer to the **data management** tutorial for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Feel free to modify it as you want.\n",
    "num_users = 100\n",
    "num_items = 25\n",
    "num_sessions = 500\n",
    "\n",
    "length_of_dataset = 10000\n",
    "# create observables/features, the number of parameters are arbitrarily chosen.\n",
    "# generate 128 features for each user, e.g., race, gender.\n",
    "user_obs = torch.randn(num_users, 128)\n",
    "# generate 64 features for each user, e.g., quality.\n",
    "item_obs = torch.randn(num_items, 64)\n",
    "# generate 10 features for each session, e.g., weekday indicator. \n",
    "session_obs = torch.randn(num_sessions, 10)\n",
    "# generate 12 features for each session user pair, e.g., the budget of that user at the shopping day.\n",
    "itemsession_obs = torch.randn(num_sessions, num_items, 12)\n",
    "item_index = torch.LongTensor(np.random.choice(num_items, size=length_of_dataset))\n",
    "user_index = torch.LongTensor(np.random.choice(num_users, size=length_of_dataset))\n",
    "session_index = torch.LongTensor(np.random.choice(num_sessions, size=length_of_dataset))\n",
    "# assume all items are available in all sessions.\n",
    "item_availability = torch.ones(num_sessions, num_items).bool()\n",
    "\n",
    "# initialize a ChoiceDataset object.\n",
    "dataset = ChoiceDataset(\n",
    "    # pre-specified keywords of __init__\n",
    "    item_index=item_index,  # required.\n",
    "    # optional:\n",
    "    num_users=num_users,\n",
    "    num_items=num_items,\n",
    "    user_index=user_index,\n",
    "    session_index=session_index,\n",
    "    item_availability=item_availability,\n",
    "    # additional keywords of __init__\n",
    "    user_obs=user_obs,\n",
    "    item_obs=item_obs,\n",
    "    session_obs=session_obs,\n",
    "    itemsession_obs=itemsession_obs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ChoiceDataset(label=[], item_index=[10000], user_index=[10000], session_index=[10000], item_availability=[500, 25], user_obs=[100, 128], item_obs=[25, 64], session_obs=[500, 10], itemsession_obs=[500, 25, 12], device=cpu)\n"
     ]
    }
   ],
   "source": [
    "print(dataset)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Conditional Logit Model\n",
    "\n",
    "Suppose that we are creating a very complicated dummy model as the following. Please note that model and dataset here are for demonstration purpose only, the model is unlikely to converge if one estimate it on this dataset.\n",
    "\n",
    "$$\n",
    "U_{uis} = \\alpha + \\beta_i + \\gamma_u + \\delta_i^\\top \\textbf{x}^{(user)}_u + \\eta^\\top \\textbf{y}^{(item)}_i + \\theta_u^\\top \\textbf{z}^{(session)}_{s} + \\kappa_i^\\top \\textbf{w}^{(itemsession)}_{is} + \\iota_u^\\top \\textbf{w}^{(itemsession)}_{is} + \\epsilon_{uis}\n",
    "$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "model = ConditionalLogitModel(formula='(1|constant) + (1|item) + (1|user) + (user_obs|item) + (item_obs|constant) + (session_obs|user) + (itemsession_obs|item) + (itemsession_obs|user)',\n",
    "                              dataset=dataset,\n",
    "                              num_users=num_users,\n",
    "                              num_items=num_items)\n",
    "\n",
    "# estimate the model... omitted in this tutorial."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ConditionalLogitModel(\n",
       "  (coef_dict): ModuleDict(\n",
       "    (intercept[constant]): Coefficient(variation=constant, num_items=25, num_users=100, num_params=1, 1 trainable parameters in total, device=cpu).\n",
       "    (intercept[item]): Coefficient(variation=item, num_items=25, num_users=100, num_params=1, 24 trainable parameters in total, device=cpu).\n",
       "    (intercept[user]): Coefficient(variation=user, num_items=25, num_users=100, num_params=1, 100 trainable parameters in total, device=cpu).\n",
       "    (user_obs[item]): Coefficient(variation=item, num_items=25, num_users=100, num_params=128, 3072 trainable parameters in total, device=cpu).\n",
       "    (item_obs[constant]): Coefficient(variation=constant, num_items=25, num_users=100, num_params=64, 64 trainable parameters in total, device=cpu).\n",
       "    (session_obs[user]): Coefficient(variation=user, num_items=25, num_users=100, num_params=10, 1000 trainable parameters in total, device=cpu).\n",
       "    (itemsession_obs[item]): Coefficient(variation=item, num_items=25, num_users=100, num_params=12, 288 trainable parameters in total, device=cpu).\n",
       "    (itemsession_obs[user]): Coefficient(variation=user, num_items=25, num_users=100, num_params=12, 1200 trainable parameters in total, device=cpu).\n",
       "  )\n",
       ")\n",
       "Conditional logistic discrete choice model, expects input features:\n",
       "\n",
       "X[intercept[constant]] with 1 parameters, with constant level variation.\n",
       "X[intercept[item]] with 1 parameters, with item level variation.\n",
       "X[intercept[user]] with 1 parameters, with user level variation.\n",
       "X[user_obs[item]] with 128 parameters, with item level variation.\n",
       "X[item_obs[constant]] with 64 parameters, with constant level variation.\n",
       "X[session_obs[user]] with 10 parameters, with user level variation.\n",
       "X[itemsession_obs[item]] with 12 parameters, with item level variation.\n",
       "X[itemsession_obs[user]] with 12 parameters, with user level variation.\n",
       "device=cpu"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Retrieving Model Parameters with the `get_coefficient()` method.\n",
    "\n",
    "In the model representation above, we can see that the model has coefficients from `intercept[constant]` to `itemsession_obs`. \n",
    "The `get_coefficient()` method allows users to retrieve the coefficient values from the model using the general syntax `model.get_coefficient(COEFFICIENT_NAME)`.\n",
    "\n",
    "For example, `model.get_coefficient('intercept[constant]')` will return the value of $\\alpha$, which is a scalar."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "tensor([0.3743])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.get_coefficient('intercept[constant]')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`model.get_coefficient('intercept[user]')` returns the array of $\\gamma_u$'s, which is a 1D array of length `num_users`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "torch.Size([100, 1])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.get_coefficient('intercept[user]').shape"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`model.get_coefficient('session_obs[user]')` returns the corresponding coefficient $\\theta_u$, which is a 2D array of shape `(num_users, num_session_features)`. Each row of the returned tensor corresponds to the coefficient vector of a user."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "torch.Size([100, 10])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.get_coefficient('session_obs[user]').shape"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lastly, the `itemsession_obs` (a 12-dimensional feature vector for each $(i, s)$ pairs) affects the utility through both $\\kappa_i$ and $\\iota_u$. For each item (except for the first item indexed with `0`, all coefficients of it are `0`), the `get_coefficient()` method returns a 2D array of shape `(num_items-1, num_itemsession_features)`.\n",
    "\n",
    "The first row of the returned tensor corresponds to the coefficient vector of the **second** item, and so on.\n",
    "\n",
    "`model.get_coefficient('itemsession_obs[user]')` provides the user-specific relationship between utility and item-session observables, $\\iota_u$, which is a 2D array of shape `(num_users, num_itemsession_features)`. Each row of the returned tensor corresponds to the coefficient vector of a user."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "torch.Size([24, 12])"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.get_coefficient('itemsession_obs[item]').shape"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "torch.Size([100, 12])"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.get_coefficient('itemsession_obs[user]').shape"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Visualizing Model Parameters\n",
    "Researchers can use any plotting library to visualize the model parameters. Here we use `matplotlib` to demonstrate how to visualize the model parameters.\n",
    "\n",
    "For example, we can plot the distribution of user fixed effect $\\gamma_u$'s as the following.\n",
    "\n",
    "1. Researcher can use the `get_coefficient()` method to retrieve the coefficient values. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "gamma = model.get_coefficient('intercept[user]')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. After estimating the model with GPU, the coefficient values are stored in the GPU memory. We need move the coefficient values to CPU memory and convert it to a numpy array before plotting."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "gamma = gamma.cpu().numpy()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. The tensor of individual fixed effects has shape (num_users, 1), you can use `squeeze()` to remove the dimension of size 1. Since we haven't updated the model in this tutorial, the coefficient values are all zeros."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,\n",
       "       0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,\n",
       "       0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,\n",
       "       0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,\n",
       "       0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,\n",
       "       0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.],\n",
       "      dtype=float32)"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gamma = gamma.squeeze()\n",
    "gamma"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "4. Researcher can use `matplotlib` to plot the distribution of the coefficient values. For example, the distribution plot of coefficients is helpful to identify potential groups of users with different preferences."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 720x360 with 1 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "fig, ax = plt.subplots(figsize=(10, 5))\n",
    "ax.hist(gamma)\n",
    "plt.show()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Nested Logit Model\n",
    "The nested logit model has a very similar interface for coefficient extraction to the conditional logit model demonstrated above.\n",
    "\n",
    "Consider a nested logit model with the same item-level model but with nest-level model incorporating user-fixed effect, category-fixed effect (specified by `(1|item)` in the `nest_formula`), and user-specific coefficient on a 64-dimensional nest-specific observable (specified by `(item_obs|user)` in the `nest_formula`).\n",
    "\n",
    "The only difference is researcher would need to retrieve the coefficients of the nested logit model using the `get_coefficient()` method with the `level` argument."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `NestedLogitModel.get_coefficient()` Method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "No `session_index` is provided, assume each choice instance is in its own session.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "JointDataset with 2 sub-datasets: (\n",
       "\tnest: ChoiceDataset(label=[], item_index=[10000], user_index=[10000], session_index=[10000], item_availability=[], item_obs=[5, 64], device=cpu)\n",
       "\titem: ChoiceDataset(label=[], item_index=[10000], user_index=[10000], session_index=[10000], item_availability=[500, 25], user_obs=[100, 128], item_obs=[25, 64], session_obs=[500, 10], itemsession_obs=[500, 25, 12], device=cpu)\n",
       ")"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nest_to_item = {\n",
    "    0: [0, 1, 2, 3, 4],\n",
    "    1: [5, 6, 7, 8, 9],\n",
    "    2: [10, 11, 12, 13, 14],\n",
    "    3: [15, 16, 17, 18, 19],\n",
    "    4: [20, 21, 22, 23, 24]\n",
    "}\n",
    "\n",
    "nest_dataset = ChoiceDataset(item_index=item_index, user_index=user_index, num_items=len(nest_to_item), num_users=num_users, item_obs=torch.randn(len(nest_to_item), 64))\n",
    "joint_dataset = JointDataset(nest=nest_dataset, item=dataset)\n",
    "joint_dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "NestedLogitModel(\n",
       "  (nest_coef_dict): ModuleDict(\n",
       "    (intercept[user]): Coefficient(variation=user, num_items=5, num_users=100, num_params=1, 100 trainable parameters in total, device=cpu).\n",
       "    (intercept[item]): Coefficient(variation=item, num_items=5, num_users=100, num_params=1, 4 trainable parameters in total, device=cpu).\n",
       "    (item_obs[user]): Coefficient(variation=user, num_items=5, num_users=100, num_params=64, 6400 trainable parameters in total, device=cpu).\n",
       "  )\n",
       "  (item_coef_dict): ModuleDict(\n",
       "    (intercept[constant]): Coefficient(variation=constant, num_items=25, num_users=100, num_params=1, 1 trainable parameters in total, device=cpu).\n",
       "    (intercept[item]): Coefficient(variation=item, num_items=25, num_users=100, num_params=1, 24 trainable parameters in total, device=cpu).\n",
       "    (intercept[user]): Coefficient(variation=user, num_items=25, num_users=100, num_params=1, 100 trainable parameters in total, device=cpu).\n",
       "    (user_obs[item]): Coefficient(variation=item, num_items=25, num_users=100, num_params=128, 3072 trainable parameters in total, device=cpu).\n",
       "    (item_obs[constant]): Coefficient(variation=constant, num_items=25, num_users=100, num_params=64, 64 trainable parameters in total, device=cpu).\n",
       "    (session_obs[user]): Coefficient(variation=user, num_items=25, num_users=100, num_params=10, 1000 trainable parameters in total, device=cpu).\n",
       "    (itemsession_obs[item]): Coefficient(variation=item, num_items=25, num_users=100, num_params=12, 288 trainable parameters in total, device=cpu).\n",
       "    (itemsession_obs[user]): Coefficient(variation=user, num_items=25, num_users=100, num_params=12, 1200 trainable parameters in total, device=cpu).\n",
       "  )\n",
       ")"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nested_model = NestedLogitModel(nest_to_item=nest_to_item,\n",
    "                                nest_formula='(1|user) + (1|item) + (item_obs|user)',\n",
    "                                item_formula='(1|constant) + (1|item) + (1|user) + (user_obs|item) + (item_obs|constant) + (session_obs|user) + (itemsession_obs|item) + (itemsession_obs|user)',\n",
    "                                num_users=num_users,\n",
    "                                dataset=joint_dataset,\n",
    "                                shared_lambda=False)\n",
    "nested_model\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "# estimate the model... omitted in this tutorial."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, you can use the following code snippet to retrieve the coefficient of the user-fixed effect in the nest level model, which is a vector with `num_users` elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "torch.Size([100, 1])"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nested_model.get_coefficient('intercept[user]', level='nest').shape"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similarly, by changing to `level='item'`, the researcher can obtain the coefficient of user-specific fixed effect in the item level model, which is also a vector with `num_users` elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "torch.Size([100, 1])"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nested_model.get_coefficient('intercept[user]', level='item').shape"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This API generalizes to all other coefficients listed above such as `itemsession_obs[item]` and `itemsession_obs[user]`.\n",
    "\n",
    "One exception is the coefficients for inclusive values, (often denoted as $\\lambda$). Researchers can retrieve the coefficient of the inclusive value by using `get_coefficient('lambda')` without specifying the `level` argument (`get_coefficient` will disregard any `level` argument if the coefficient name is `lambda`). The returned value is a scalar if `shared_lambda` is `True`, and a 1D array of length `num_nests` if `shared_lambda` is `False`. In our case, the returned value is an array of length five (we have five nests in this model)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "tensor([0.5000, 0.5000, 0.5000, 0.5000, 0.5000])"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nested_model.get_coefficient('lambda')"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "ml",
   "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.9.7"
  },
  "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": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}