choiceprob_logit: Calculate logit choice probabilities

In choicedata: Working with Choice Data

Calculate logit choice probabilities

Description

These helper functions compute logit choice probabilities for unordered and ordered outcomes. Panel inputs reuse the observation-level logit formulae, which remain valid because the logit error term is independent across occasions. Latent class models are supported via weighted averages of class-specific probabilities. When Omega is supplied, the coefficients are assumed to follow a multivariate normal distribution and the resulting probabilities are evaluated by averaging over simulation draws.

Usage

choiceprob_logit(
  X,
  y = NULL,
  Tp = NULL,
  beta,
  Omega = NULL,
  gamma = NULL,
  weights = NULL,
  input_checks = TRUE,
  ordered = !is.null(gamma),
  ranked = !ordered && !is.null(y) && length(y) > 0 && length(y[[1]]) > 1,
  panel = !is.null(Tp) && any(Tp > 1),
  lc = !is.null(weights),
  draws = NULL,
  n_draws = 200
)

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.
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.
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()] Optional class weights for latent class specifications.
input_checks	[logical(1)] Perform input checks. Set to FALSE to skip them.
ordered, ranked, panel, lc	[logical(1)] Flags indicating whether the specification is ordered, ranked, panel, or latent class. These defaults are inferred from the other inputs so callers typically do not need to override them.
draws	[NULL | matrix | list] Optional simulation draws for the random coefficients when Omega is not NULL. A matrix provides shared draws for all classes; a list can supply class-specific draw matrices.
n_draws	[integer(1)] Number of draws to generate when draws is NULL and Omega is provided.

Value

A numeric vector with the choice probabilities for the observed choices when y is supplied. If y is NULL, a matrix with one row per observation and one column per alternative is returned.

choicedata documentation built on Nov. 5, 2025, 5:46 p.m.