Skip to contents

Calculate probit choice probabilities

Source: R/choice_probabilities.R
choiceprob_probit.Rd

These helper functions calculate probit choice probabilities for various scenarios:

  • in the regular (choiceprob_mnp_*), ordered (*_ordered), and ranked (ranked = TRUE) case,

  • in the normally mixed (choiceprob_mmnp_*) and latent class (*_lc) case,

  • for panel data (*_panel),

  • based on the full likelihood (cml = "no"), the full pairwise composite marginal likelihood (cml = "fp"), and the adjacent pairwise composite marginal likelihood (cml = "ap"),

  • for the observed choices or for all alternatives (if y is NULL).

The function choiceprob_probit() is the general API which calls the specialized functions and can perform input checks.

Usage

choiceprob_probit(
  X,
  y = NULL,
  Tp = NULL,
  cml = "no",
  beta,
  Omega = NULL,
  Sigma,
  gamma = NULL,
  weights = NULL,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0,
  input_checks = TRUE,
  ordered = !is.null(gamma),
  ranked = if (!ordered && !is.null(y) && isTRUE(length(y) > 0)) {
     length(y[[1]]) >
    1
 } else {
     FALSE
 },
  mixed = !is.null(Omega),
  panel = mixed & !is.null(Tp) & any(Tp > 1),
  lc = !is.null(weights)
)

choiceprob_mnp(
  X,
  y,
  beta,
  Sigma,
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0,
  ranked = FALSE
)

choiceprob_mnp_ordered(X, y, beta, Sigma, gamma, lower_bound = 0)

choiceprob_mmnp(
  X,
  y,
  beta,
  Omega,
  Sigma,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0,
  ranked = FALSE
)

choiceprob_mmnp_ordered(
  X,
  y,
  beta,
  Omega,
  Sigma,
  gamma,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  lower_bound = 0
)

choiceprob_mmnp_lc(
  X,
  y,
  beta,
  Omega,
  Sigma,
  weights,
  re_position = utils::tail(seq_along(beta[[1]]), nrow(Omega[[1]])),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0,
  ranked = FALSE
)

choiceprob_mmnp_ordered_lc(
  X,
  y,
  beta,
  Omega,
  Sigma,
  gamma,
  weights,
  re_position = utils::tail(seq_along(beta[[1]]), nrow(Omega[[1]])),
  lower_bound = 0
)

choiceprob_mmnp_panel(
  X,
  y,
  Tp,
  cml,
  beta,
  Omega,
  Sigma,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0,
  ranked = FALSE
)

choiceprob_mmnp_ordered_panel(
  X,
  y,
  Tp,
  cml,
  beta,
  Omega,
  Sigma,
  gamma,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0
)

choiceprob_mmnp_panel_lc(
  X,
  y,
  Tp,
  cml,
  beta,
  Omega,
  Sigma,
  weights,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0,
  ranked = FALSE
)

choiceprob_mmnp_ordered_panel_lc(
  X,
  y,
  Tp,
  cml,
  beta,
  Omega,
  Sigma,
  gamma,
  weights,
  re_position = utils::tail(seq_along(beta), nrow(Omega)),
  gcdf = pmvnorm_cdf_default,
  lower_bound = 0
)

Arguments

X

[list(N)]
A list of length N (number observations) of design matrices, each of dimension J (number alternatives) times P (number effects).

In the ordered case (ordered = TRUE), the design matrices are of dimension 1 times P.

y

[list(N) | NULL]
A list of length N (number observations) of single integers from 1 to J (number alternatives).

In the ranked case (ranked = TRUE), the list entries each must be a permutation of 1:J, where the higher-ranked alternatives are in front.

In the non-panel case (panel = FALSE), y can also be NULL, in which case probabilities are calculated for all choice alternatives. In the ranked case (ranked = TRUE), if y is NULL, only first place choice probabilities are computed, which is equivalent to computing choice probabilities in the regular (maximum utility) model.

Tp

[NULL | integer(N)]
The panel identifier of length N (number observations) for panel data. The number Tp[1] indicates, that the first Tp[1] observations in X and y belong to decider 1, the next Tp[2] observations belong to decider 2, and so on.

Can be NULL for no panel data.

cml

[character(1)]
The composite marginal likelihood (CML) type for panel data. It can be one of "no" (full likelihood), "fp" (full pairwise), or "ap" (adjacent pairwise).

beta

[numeric(P) | list]
The coefficient vector of length P (number effects) for computing the systematic utility \(V = X\beta\).

In the latent class case (lc = TRUE), beta is a list of length C of such coefficients, where C is the number of latent classes.

Omega

[matrix(nrow = P_r, ncol = P_r) | NULL | list]
The covariance matrix of random effects of dimension P_r times P_r, where P_r less than P is the number of random effects.

Can be NULL for no random effects.

In the latent class case (lc = TRUE), Omega is a list of length C of such covariance matrices, where C is the number of latent classes.

Sigma

[matrix(nrow = J, ncol = J) | numeric(1)]
The covariance matrix of dimension J times J (number alternatives) for the Gaussian error term \(\epsilon = U - V\).

In the ordered case (ordered = TRUE), Sigma is a single, non-negative numeric.

gamma

[NULL | numeric(J - 1)]
Only relevant in the ordered case (ordered = TRUE). It defines the non-decreasing boundaries of the utility categories.

The event \(U \leq \gamma_j\) means that alternative \(j\) is chosen, while \(U > \gamma_{J - 1}\) means that alternative \(J\) is chosen.

weights

[NULL | numeric(C)]
The weights for the latent classes in the latent class case (lc = TRUE).

re_position

[integer(P_r)]
The index positions of the random effects in the coefficient vector beta.

By default, the last \(P_r\) entries of beta are considered as random, where \(P_r\) is the dimension of Omega.

gcdf

[function(upper, corr)]
A function that computes (or approximates) the centered Gaussian CDF (mean is zero) based on the upper integration limit upper and correlation matrix corr. The output is expected to be a single numeric value between zero and one.

In the no-panel (panel = FALSE) ordered case (ordered = TRUE), stats::pnorm() is used to calculate the one-dimensional Gaussian CDF.

lower_bound

[numeric(1)]
A lower bound for the probabilities for numerical reasons. Probabilities are returned as max(prob, lower_bound).

input_checks

[logical(1)]
Perform input checks. Set to FALSE to skip them.

ordered, ranked, mixed, panel, lc

[logical(1)]
Flags indicating the model type. These are determined automatically based on the input arguments.

Value

A numeric vector of length N, the probabilities for the observed choices y.

In the panel case (panel = TRUE), the probabilities of the observed choice sequence of length length(Tp).

If y is NULL and in the non-panel case (panel = FALSE), a matrix of dimension N times J, the probabilities for all alternatives. In the ranked case (ranked = TRUE), only first place choice probabilities are computed, which is equivalent to computing choice probabilities in the regular (maximum utility) model.