docs: add mixed mnl example to documentation

docs/examples/mixed_mnl.ipynb

@@ -0,0 +1,144 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Mixed logit"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This example shows a multinomial logit model with one random Beta variable for time. We use a \"random coefficients\" method of defining the model and a simulation based estimation:\n",
+    "```\n",
+    "Beta(\"b_time\") + Beta(\"s_time\") * RandomDraws(\"rnd_time\", \"lognormal\", 100)\n",
+    "```\n",
+    "\n",
+    "The arguments for `RandomDraws(name, draw_type, draws)` are:\n",
+    "\n",
+    "- name (`str`) the name of the draw\n",
+    "- draw type (`str`) the distribution of the draws\n",
+    "- draws (`int`) the number of random draws to sample from"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#import packages\n",
+    "import pandas as pd\n",
+    "from pycmtensor.dataset import Dataset\n",
+    "from pycmtensor.expressions import Beta, RandomDraws\n",
+    "from pycmtensor.models import MNL\n",
+    "\n",
+    "\n",
+    "# load data\n",
+    "lpmc = pd.read_csv(\"../../data/lpmc.dat\", sep=\"\\t\")\n",
+    "ds = Dataset(df=lpmc, choice=\"travel_mode\")\n",
+    "ds.split(0.8)\n",
+    "\n",
+    "\n",
+    "# Beta parameters\n",
+    "asc_walk = Beta(\"asc_walk\", 0.0, None, None, 1)\n",
+    "asc_cycle = Beta(\"asc_cycle\", 0.0, None, None, 0)\n",
+    "asc_pt = Beta(\"asc_pt\", 0.0, None, None, 0)\n",
+    "asc_drive = Beta(\"asc_drive\", 0.0, None, None, 0)\n",
+    "b_cost = Beta(\"b_cost\", 0.0, None, None, 0)\n",
+    "b_time = Beta(\"b_time\", 0.0, None, None, 0)\n",
+    "s_time = Beta(\"s_time\", 0.5, None, None, 0)\n",
+    "b_purpose = Beta(\"b_purpose\", 0.0, None, None, 0)\n",
+    "b_licence = Beta(\"b_licence\", 0.0, None, None, 0)\n",
+    "b_car_own = Beta(\"b_car_own\", 0.0, None, None, 0)\n",
+    "\n",
+    "\n",
+    "# additional parameter for variance of b_time\n",
+    "s_time = Beta(\"s_time\", 0.5, None, None, 0)\n",
+    "\n",
+    "\n",
+    "# define the sampling variable\n",
+    "rnd_time = RandomDraws('rnd_time', 'lognormal', 100)\n",
+    "\n",
+    "\n",
+    "# composite variables\n",
+    "dur_pt = ds[\"dur_pt_rail\"] + ds[\"dur_pt_bus\"] + ds[\"dur_pt_int\"]\n",
+    "cost_drive = ds[\"cost_driving_fuel\"] + ds[\"cost_driving_ccharge\"]\n",
+    "\n",
+    "\n",
+    "# define the random beta time coefficient\n",
+    "b_time_rnd = b_time + s_time * rnd_time\n",
+    "\n",
+    "\n",
+    "# utility functions\n",
+    "U_walk = asc_walk + b_time_rnd * ds[\"dur_walking\"]\n",
+    "U_cycle = asc_cycle + b_time_rnd * ds[\"dur_cycling\"] \n",
+    "U_pt = asc_pt + b_time_rnd * dur_pt + b_cost * ds[\"cost_transit\"]\n",
+    "U_drive = (asc_drive + b_time_rnd * ds[\"dur_driving\"] + b_cost * cost_drive \n",
+    "        + b_licence * ds[\"driving_license\"] + b_purpose * ds[\"purpose\"] \n",
+    "\t\t+ b_car_own * ds[\"car_ownership\"])\n",
+    "\n",
+    "U = [U_walk, U_cycle, U_pt, U_drive]\n",
+    "\n",
+    "\n",
+    "# the choice model is MNL\n",
+    "mymodel = MNL(ds, locals(), U)\n",
+    "\n",
+    "\n",
+    "# estimate the model\n",
+    "from pycmtensor.models import train\n",
+    "train(mymodel, ds)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following code displays the results of the model estimation, model correlation matrices, predicitons, and elasticities"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(mymodel.results.beta_statistics())\n",
+    "print(mymodel.results.model_statistics())\n",
+    "print(mymodel.results.benchmark())\n",
+    "\n",
+    "# correlation matrix\n",
+    "print(mymodel.results.model_correlation_matrix())\n",
+    "print(mymodel.results.model_robust_correlation_matrix())\n",
+    "\n",
+    "# probability prediction\n",
+    "prob = mymodel.predict(ds, return_probabilities=True)\n",
+    "pd.DataFrame(prob)\n",
+    "\n",
+    "# choice prediction\n",
+    "choice = mymodel.predict(ds, return_probabilities=False)\n",
+    "pd.DataFrame(choice)\n",
+    "\n",
+    "# elasticity w.r.t. choice 1\n",
+    "elas = mymodel.elasticities(ds, wrt_choice=1)\n",
+    "pd.DataFrame(elas)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "pycmtensor-dev",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.4"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/examples/mnl.ipynb

@@ -46,11 +46,13 @@
     "cost_drive = ds[\"cost_driving_fuel\"] + ds[\"cost_driving_ccharge\"]\n",
     "\n",
     "\n",
-    "# utility fuctions\n",
+    "# utility functions\n",
     "U_walk = asc_walk + b_time * ds[\"dur_walking\"]\n",
     "U_cycle = asc_cycle + b_time * ds[\"dur_cycling\"] \n",
     "U_pt = asc_pt + b_time * dur_pt + b_cost * ds[\"cost_transit\"]\n",
-    "U_drive = asc_drive + b_time * ds[\"dur_driving\"] + b_licence * ds[\"driving_license\"] + b_cost * cost_drive + b_purpose * ds[\"purpose\"]\n",
+    "U_drive = (asc_drive + b_time * ds[\"dur_driving\"] + b_cost * cost_drive \n",
+    "        + b_licence * ds[\"driving_license\"] + b_purpose * ds[\"purpose\"] \n",
+    "\t\t+ b_car_own * ds[\"car_ownership\"])\n",
     "\n",
     "U = [U_walk, U_cycle, U_pt, U_drive]\n",
     "\n",

mkdocs.yml

@@ -9,6 +9,7 @@ nav:
     - Troubleshooting & tips: getting_started/troubleshooting.md
   - Examples: 
     - Multnomial logit: examples/mnl.ipynb
+    - Mixed logit: examples/mixed_mnl.ipynb
   - User guide:
     - User guide: user_guide/index.md
     - Configuration: user_guide/configuration.md