Calculate logit choice probabilities

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.