choiceprob_probit: Calculate probit choice probabilities
In choicedata: Working with Choice Data

choiceprob_probit

R Documentation

Calculate probit choice probabilities

Description

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.