---
title: "Estimating Multinomial Logit Models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Estimating Multinomial Logit Models}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
bibliography: "`r here::here('vignettes', 'library.bib')`"
---

```{r setup, include=FALSE, message=FALSE, warning=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  warning = FALSE,
  message = FALSE,
  fig.retina = 3,
  comment = "#>"
)
```

This vignette demonstrates an example of how to use the `logitr()` function to estimate multinomial logit (MNL) models with preference space and WTP space utility parameterizations.

# The data

```{r, child='../man/rmdchunks/yogurtDataDescription.Rmd'}
```

In the utility models described below, the data variables are represented as follows:

```{r, child='../man/rmdchunks/mnlPrefExampleTable.Rmd'}
```

# Preference space model

This example will estimate the following homogeneous multinomial logit model in the preference space:

```{r, child='../man/rmdchunks/mnlPrefExample.Rmd'}
```

where the parameters $\alpha$, $\beta_1$, $\beta_2$, $\beta_3$, and $\beta_4$ have units of utility.

Estimate the model using the `logitr()` function:

```{r}
library("logitr")

mnl_pref <- logitr(
  data    = yogurt,
  outcome = 'choice',
  obsID   = 'obsID',
  pars    = c('price', 'feat', 'brand')
)
```

Print a summary of the results:

```{r}
summary(mnl_pref)
```

View the estimated model coefficients:

```{r}
coef(mnl_pref)
```

Compute the WTP implied from the preference space model:

```{r}
wtp_mnl_pref <- wtp(mnl_pref, scalePar =  "price")
wtp_mnl_pref
```

# WTP space model

This example will estimate the following homogeneous multinomial logit model in the WTP space:

```{r, child='../man/rmdchunks/mnlWtpExample.Rmd'}
```

where the parameters $\omega_1$, $\omega_2$, $\omega_3$, and $\omega_4$ have units of dollars and $\lambda$ is the scale parameter.

Estimate the model using the `logitr()` function:

```{r}
mnl_wtp <- logitr(
  data    = yogurt,
  outcome = 'choice',
  obsID   = 'obsID',
  pars    = c('feat', 'brand'),
  scalePar = 'price',
  # Since WTP space models are non-convex, run a multistart
  numMultiStarts = 10,
  # Use the computed WTP from the preference space model as the starting
  # values for the first run:
  startVals = wtp_mnl_pref$Estimate
)
```

Print a summary of the results:

```{r}
summary(mnl_wtp)
```

View the estimated model coefficients:

```{r}
coef(mnl_wtp)
```

# Compare WTP from both models

Since WTP space models are non-convex, you cannot be certain that the model reached a global solution, even when using a multi-start. However, homogeneous models in the _preference_ space are convex, so you are guaranteed to find the global solution in that space. Therefore, it can be useful to compute the WTP from the preference space model and compare it against the WTP from the WTP space model. If the WTP values and log-likelihood values from the two model spaces are equal, then the WTP space model is likely at a global solution.

To compare the WTP and log-likelihood values between the preference space and WTP space models, use the `wtpCompare()` function:

```{r}
wtpCompare(mnl_pref, mnl_wtp, scalePar = 'price')
```

# References