Use this function to estimate multinomial (MNL) and mixed logit (MXL)
models with "Preference" space or "Willingness-to-pay" (WTP) space utility
parameterizations. The function includes an option to run a multistart
optimization loop with random starting points in each iteration, which is
useful for non-convex problems like MXL models or models with WTP space
utility parameterizations. The main optimization loop uses the `nloptr()`

function to minimize the negative log-likelihood function.

logitr( data, outcome, obsID, pars, price = NULL, randPars = NULL, randPrice = NULL, modelSpace = "pref", weights = NULL, panelID = NULL, clusterID = NULL, robust = FALSE, startParBounds = c(-1, 1), startVals = NULL, numMultiStarts = 1, useAnalyticGrad = TRUE, scaleInputs = TRUE, standardDraws = NULL, numDraws = 50, vcov = FALSE, predict = TRUE, options = list(print_level = 0, xtol_rel = 1e-06, xtol_abs = 1e-06, ftol_rel = 1e-06, ftol_abs = 1e-06, maxeval = 1000, algorithm = "NLOPT_LD_LBFGS"), choice, parNames, choiceName, obsIDName, priceName, weightsName, clusterName, cluster )

data | The data, formatted as a |
---|---|

outcome | The name of the column that identifies the outcome variable,
which should be coded with a |

obsID | The name of the column that identifies each observation. |

pars | The names of the parameters to be estimated in the model.
Must be the same as the column names in the |

price | The name of the column that identifies the price variable.
Required for WTP space models. Defaults to |

randPars | A named vector whose names are the random parameters and
values the distribution: |

randPrice | The random distribution for the price parameter: |

modelSpace | Set to |

weights | The name of the column that identifies the weights to be
used in model estimation. Defaults to |

panelID | The name of the column that identifies the individual (for
panel data where multiple observations are recorded for each individual).
Defaults to |

clusterID | The name of the column that identifies the cluster
groups to be used in model estimation. Defaults to |

robust | Determines whether or not a robust covariance matrix is
estimated. Defaults to |

startParBounds | sets the |

startVals | is vector of values to be used as starting values for the
optimization. Only used for the first run if |

numMultiStarts | is the number of times to run the optimization loop,
each time starting from a different random starting point for each parameter
between |

useAnalyticGrad | Set to |

scaleInputs | By default each variable in |

standardDraws | By default, a new set of standard normal draws are
generated during each call to |

numDraws | The number of Halton draws to use for MXL models for the
maximum simulated likelihood. Defaults to |

vcov | Set to |

predict | If |

options | A list of options for controlling the |

choice | No longer used as of v0.4.0 - if provided, this is passed
to the |

parNames | No longer used as of v0.2.3 - if provided, this is passed
to the |

choiceName | No longer used as of v0.2.3 - if provided, this is passed
to the |

obsIDName | No longer used as of v0.2.3 - if provided, this is passed
to the |

priceName | No longer used as of v0.2.3 - if provided, this is passed
to the |

weightsName | No longer used as of v0.2.3 - if provided, this is passed
to the |

clusterName | No longer used as of v0.2.3 - if provided, this is passed
to the |

cluster | No longer used as of v0.2.3 - if provided, this is passed
to the |

The function returns a list object containing the following objects.

Value | Description |

`coefficients` | The model coefficients at convergence. |

`logLik` | The log-likelihood value at convergence. |

`nullLogLik` | The null log-likelihood value (if all coefficients are 0). |

`gradient` | The gradient of the log-likelihood at convergence. |

`hessian` | The hessian of the log-likelihood at convergence. |

`probabilities` | Predicted probabilities. Not returned if `predict = FALSE` . |

`fitted.values` | Fitted values. Not returned if `predict = FALSE` . |

`residuals` | Residuals. Not returned if `predict = FALSE` . |

`startPars` | The starting values used. |

`multistartNumber` | The multistart run number for this model. |

`multistartSummary` | A summary of the log-likelihood values for each multistart run (if more than one multistart was used). |

`time` | The user, system, and elapsed time to run the optimization. |

`iterations` | The number of iterations until convergence. |

`message` | A more informative message with the status of the optimization result. |

`status` | An integer value with the status of the optimization (positive values are successes). Use `statusCodes()` for a detailed description. |

`call` | The matched call to `logitr()` . |

`inputs` | A list of the original inputs to `logitr()` . |

`data` | A list of the original data provided to `logitr()` broken up into components used during model estimation. |

`numObs` | The number of observations. |

`numParams` | The number of model parameters. |

`freq` | The frequency counts of each alternative. |

`modelType` | The model type, `'mnl'` for multinomial logit or `'mxl'` for mixed logit. |

`weightsUsed` | `TRUE` or `FALSE` for whether weights were used in the model. |

`numClusters` | The number of clusters. |

`parSetup` | A summary of the distributional assumptions on each model parameter (`"f"` ="fixed", `"n"` ="normal distribution", `"ln"` ="log-normal distribution"). |

`parIDs` | A list identifying the indices of each parameter in `coefficients` by a variety of types. |

`scaleFactors` | A vector of the scaling factors used to scale each coefficient during estimation. |

`standardDraws` | The draws used during maximum simulated likelihood (for MXL models). |

`options` | A list of options for controlling the `nloptr()` optimization. Run `nloptr::nloptr.print.options()` for details. |

The the `options`

argument is used to control the detailed behavior of the
optimization and must be passed as a list, e.g. `options = list(...)`

.
Below are a list of the default options, but other options can be included.
Run `nloptr::nloptr.print.options()`

for more details.

Argument | Description | Default |

`xtol_rel` | The relative `x` tolerance for the `nloptr` optimization loop. | `1.0e-6` |

`xtol_abs` | The absolute `x` tolerance for the `nloptr` optimization loop. | `1.0e-6` |

`ftol_rel` | The relative `f` tolerance for the `nloptr` optimization loop. | `1.0e-6` |

`ftol_abs` | The absolute `f` tolerance for the `nloptr` optimization loop. | `1.0e-6` |

`maxeval` | The maximum number of function evaluations for the `nloptr` optimization loop. | `1000` |

`algorithm` | The optimization algorithm that `nloptr` uses. | `"NLOPT_LD_LBFGS"` |

`print_level` | The print level of the `nloptr` optimization loop. | `0` |

# For more detailed examples, visit # https://jhelvy.github.io/logitr/articles/ library(logitr) # Estimate a MNL model in the Preference space mnl_pref <- logitr( data = yogurt, outcome = "choice", obsID = "obsID", pars = c("price", "feat", "brand") )#>#># Estimate a MNL model in the WTP space, using a 10-run multistart mnl_wtp <- logitr( data = yogurt, outcome = "choice", obsID = "obsID", pars = c("feat", "brand"), price = "price", modelSpace = "wtp", numMultiStarts = 10 )#>#>#>#>#>#>#>#>#>#>#># Estimate a MXL model in the Preference space with "feat" # following a normal distribution mxl_pref <- logitr( data = yogurt, outcome = "choice", obsID = "obsID", pars = c("price", "feat", "brand"), randPars = c(feat = "n", brand = "n") )#>#>