Introduction to RprobitB

Installing RprobitB

To install the latest version of RprobitB, run install.packages("RprobitB") in your R console.

Using RprobitB

To use RprobitB, follow these steps:

1. Specify the model, see below for details.
2. Run RprobitB::rpb(<list of model specifications>).
3. You get on-screen information and model results in an output folder.

LCMMNP model

Assume that we observe the choices of \(N\) decision makers which decide between \(J\) alternatives at each of \(T\) choice occasions.¹ Specific to each decision maker, alternative and choice occasion, we furthermore observe \(P_f+P_r\) choice attributes that we use to explain the choices. The first \(P_f\) attributes are connected to fixed coefficients, the other \(P_r\) attributes to random coefficients following a joint distribution mixed across decision makers. Person \(n\)’s utility \(\tilde{U}_{ntj}\) for alternative \(j\) at choice occasion \(t\) is modelled as \[\begin{equation} \tilde{U}_{ntj} = \tilde{W}_{ntj}'\alpha + \tilde{X}_{ntj}'\beta_n + \tilde{\epsilon}_{ntj} \end{equation}\] for \(n=1,\dots,N\), \(t=1,\dots,T\) and \(j=1,\dots,J\), where

• \(\tilde{W}_{ntj}\) is a vector of \(P_f\) characteristics of \(j\) as faced by \(n\) at \(t\) corresponding to the fixed coefficient vector \(\alpha \in {\mathbb R}^{P_f}\),
• \(\tilde{X}_{ntj}\) is a vector of \(P_r\) characteristics of \(j\) as faced by \(n\) at \(t\) corresponding to the random, decision maker-specific coefficient vector \(\beta_n \in {\mathbb R}^{P_r}\), where \(\beta_n\) is distributed according to some \(P_r\)-variate distribution \(g_{P_r}\),
• and \((\tilde{\epsilon}_{nt:}) = (\tilde{\epsilon}_{nt1},\dots,\tilde{\epsilon}_{ntJ})' \sim \text{MVN}_{J} (0,\tilde{\Sigma})\) is the models’ error term vector for \(n\) at \(t\), which in the probit model is assumed to be multivariate normally distributed with zero mean and covariance matrix \(\tilde{\Sigma}\).

As is well known, any utility model needs to be normalized with respect to level and scale in order to be identified. Therefore, we consider the transformed model \[\begin{equation} U_{ntj} = W_{ntj}'\alpha + X_{ntj}'\beta_n + \epsilon_{ntj}, \end{equation}\] \(n=1,\dots,N\), \(t=1,\dots,T\) and \(j=1,\dots,J-1\), where (choosing \(J\) as the reference alternative) \(U_{ntj}=\tilde{U}_{ntj} - \tilde{U}_{ntJ}\), \(W_{ntj}=\tilde{W}_{ntj}-\tilde{W}_{ntJ}\), \(X_{ntj}=\tilde{X}_{ntj}-\tilde{X}_{ntJ}\) and \(\epsilon_{ntj}=\tilde{\epsilon}_{ntj}-\tilde{\epsilon}_{ntJ}\), where \((\epsilon_{nt:}) = (\epsilon_{nt1},...,\epsilon_{nt(J-1)})' \sim \text{MVN}_{J-1} (0,\Sigma)\) and \(\Sigma\) denotes a covariance matrix with the top-left element restricted to one. While taking utility differences in order to normalize the model with respect to level is a standard procedure, alternatives to fixing an error term variance in order to normalize with respect to scale exist, for example fixing an element of \(\alpha\).

Let \(y_{nt}=j\) denote the event that decision maker \(n\) chooses alternative \(j\) at choice occasion \(t\). Assuming utility maximizing behaviour of the decision makers, the decisions are linked to the utilities via \[\begin{equation} y_{nt} = \sum_{j=1}^{J-1} j\cdot 1 \left (U_{ntj}=\max_i U_{nti}>0 \right) + J \cdot 1\left (U_{ntj}<0 ~\text{for all}~j\right), \end{equation}\] where \(1(A)\) equals \(1\) if condition \(A\) is true and \(0\) else.

We approximate the mixing distribution \(g_{P_r}\) for the random coefficients \(\beta=(\beta_n)_{n}\) by a mixture of \(P_r\)-variate normal densities \(\phi_{P_r}\) with mean vectors \(b=(b_c)_{c}\) and covariance matrices \(\Omega=(\Omega_c)_{c}\) using \(C\) components, i.e. \[\begin{equation} \beta_n\mid b,\Omega \sim \sum_{c=1}^{C} s_c \phi_{P_r} (\cdot \mid b_c,\Omega_c), \end{equation}\] where \((s_c)_{c}\) are weights satisfying \(0 < s_c\leq 1\) for \(c=1,\dots,C\) and \(\sum_c s_c=1\). One interpretation of the latent class model is obtained by introducing variables \(z=(z_n)_n\) allocating each decision maker \(n\) to class \(c\) with probability \(s_c\), i.e. \[\begin{equation} \text{Prob}(z_n=c)=s_c \quad \text{and} \quad \beta_n \mid z,b,\Omega \sim \phi_{P_r}(\cdot \mid b_{z_n},\Omega_{z_n}). \end{equation}\] We call this model the latent class mixed multinomial probit (LCMMNP) model.²

Latent class updating scheme

Updating the number \(C\) of latent classes is done within the algorithm by executing the following weight-based updating scheme.

• Class \(c\) is removed, if \(s_c<\epsilon_{\text{min}}\), i.e. if the class weight \(s_c\) drops below some threshold \(\epsilon_{\text{min}}\). This case indicates that class \(c\) has a negligible impact on the mixing distribution.
• Class \(c\) is splitted into two classes \(c_1\) and \(c_2\), if \(s_c>\epsilon_\text{max}\). This case indicates that class \(c\) has a high influence on the mixing distribution whose approximation can potentially be improved by increasing the resolution in directions of high variance. Therefore, the class means \(b_{c_1}\) and \(b_{c_2}\) of the new classes \(c_1\) and \(c_2\) are shifted in opposite directions from the class mean \(b_c\) of the old class \(c\) in the direction of the highest variance.
• Two classes \(c_1\) and \(c_2\) are joined to one class \(c\), if \(\lVert b_{c_1} - b_{c_2} \rVert<\epsilon_{\text{distmin}}\), i.e. if the euclidean distance between the class means \(b_{c_1}\) and \(b_{c_2}\) drops below some threshold \(\epsilon_{\text{distmin}}\). This case indicates location redundancy which should be repealed. The parameters of \(c\) are assigned by adding the values of \(s\) from \(c_1\) and \(c_2\) and averaging the values for \(b\) and \(\Omega\).

Specifying a LCMMNP model in RprobitB

RprobitB specifications are grouped in the named lists

• model (model information),
• data (data information),
• parm (true parameter values),
• lcus (latent class updating scheme parameters),
• init (initial values for the Gibbs sampler),
• prior (prior parameters),
• mcmc (Markov chain Monte Carlo parameters),
• norm (normalization information),
• out (output settings).

You can either specify none, all, or selected parameters. Unspecified parameters are set to default values.

Default specifications of RprobitB

Example: Simulated data

The code below fits a mixed multinomial probit model with

• P_f = 1 fixed
  
• and P_r = 2 random coefficients

to simulated data with

• N = 100 decision makers,
• variable choice occasions between T = 10 and T = 20,
• J = 3 choice alternatives,
• and C = 2 true latent classes.

The number of latent classes is updated, because do_lcus = TRUE is set. The Gibbs sampler draws R = 20000 samples. By default, the model is named id = "test" and results are saved in rdir = "tempdir()" (the path of the per-session temporary directory).

set.seed(1)

### model specification
model = list("N" = 100, "T" = sample(10:20,100,replace=TRUE), "J" = 3, "P_f" = 1, "P_r" = 2, "C" = 2)
lcus  = list("do_lcus" = TRUE)
mcmc  = list("R" = 20000)

### start estimation (about 3 minutes computation time)
RprobitB::rpb("model" = model, "lcus" = lcus, "mcmc" = mcmc)

Example: Empirical data

The code below fits a mixed multinomial probit model with P_f = 2 fixed and P_r = 2 random coefficients to the “Train” dataset of the mlogit package with

• covariates in the columns "cov_col" = 4:11,
• “price” and “comfort” linked to fixed and “time” and “change” linked to random coefficients via "cov_ord" = c("price","comfort","time","change") (remember that fixed coefficients come first),
• and z-standardized covariates ("cov_zst" = TRUE).

For normalization, the price coefficient ("parameter" = "a", "index" = 1) is fixed to "value" = -1.

### load Train data
data("Train", package = "mlogit")

### model specification
model = list("P_f" = 2, "P_r" = 2)
data  = list("data_raw" = Train, "cov_col" = 4:11, "cov_ord" = c("price","comfort","time","change"), "cov_zst" = TRUE)
lcus  = list("do_lcus" = TRUE)
mcmc  = list("R" = 1e5)
norm  = list("parameter" = "a", "index" = 1, "value" = -1)
out   = list("id" = "train", "pp" = TRUE)

### start estimation (about 20 minutes computation time)
RprobitB::rpb("model" = model, "data" = data, "lcus" = lcus, "mcmc" = mcmc, "norm" = norm, "out" = out)

On-screen information

During estimation, you get the following on-screen information:

• a summary of the model, normalization, and Gibbs sampler settings, and (if lcus[["do_lcus"]]=TRUE) the latent class updating scheme parameters
• the sampling progress with expected time for completion (ETA)
• a summary of the posterior distribution (where x. denotes latent class number x in case of lcus[["do_lcus"]]=TRUE) with
  • the true parameter values (only for simulated data)
  • the posterior mean
  • the posterior standard deviation
  • the 5% and 95% quantile of the posterior
  • the Gelman-Rubin statistic (R^)
• the model’s WAIC value (if out[["waic"]]=TRUE)
• the path to the model results

Model results

In the output folder out[["rdir"]]/out[["id"]], you can find the files

• protocol.txt, a copy of the on-screen information,
• several .rds-files of inputs and outputs,
• and different model visualizations:
  • acf.pdf, the autocorrelation of the Gibbs samples with the effective sample size,
  • marginal.pdf, estimated marginal distributions,
  • trace.pdf, plots of the traces of the Gibbs samples,
  • and, if model[["P_r"]] > 0, contour.pdf, contour plot and progress contour plots (only if out[["pp"]] = TRUE) of the Gibbs samples.