Define and compute choice likelihood — choice

These functions prepare and evaluate the likelihood contribution of observed choices for a given choice model.

choice_likelihood() pre-computes the design matrices and choice indices implied by choice_data and choice_effects. The returned object stores these quantities so that repeated likelihood evaluations during maximum likelihood estimation avoid redundant work.
compute_choice_likelihood() evaluates the (log-)likelihood for given choice_parameters and a pre-computed choice_likelihood object.

Usage

choice_likelihood(
  choice_data,
  choice_effects,
  choice_identifiers = extract_choice_identifiers(choice_data),
  input_checks = TRUE,
  ...
)

compute_choice_likelihood(
  choice_parameters,
  choice_likelihood,
  logarithm = TRUE,
  negative = FALSE,
  aggregate = c("total", "decider", "occasion"),
  ...
)

Arguments

choice_data

[choice_data]
A choice_data object.

choice_effects

[choice_effects]
A choice_effects object.

choice_identifiers

[choice_identifiers]
A choice_identifiers object. The default is extracted from choice_data.

input_checks

[logical(1)]
Check the pre-computed design matrices and choice indices against the parameters on the first likelihood evaluation? Later evaluations skip these checks because the pre-computed quantities do not change.

...

Additional arguments for the probability computation:

n_draws [integer(1)]: The number of draws for simulated probabilities, which are required for mixed logit models and for mixed probit models with non-normal random effects. The default is 200.
draws [matrix]: A matrix of standard normal draws with one column per random effect that replaces the generated draws.
cml [character(1)]: Composite marginal likelihood for panel probit models. Either "no" (default, the full likelihood), "fp" (all pairs of choice occasions), or "ap" (adjacent pairs of choice occasions).
ghk_draws [integer(1)]: The number of draws of the GHK simulator for multivariate normal probabilities in probit models, see pmvnorm. Probabilities of up to three dimensions are computed exactly; higher dimensions use the GHK simulator on a fixed sequence of quasi-random Halton points. The default is 500.

choice_parameters

[choice_parameters | numeric() | list()]
A choice_parameters object.

A numeric vector in optimization space is also accepted and converted with switch_parameter_space().

A list of either representation is evaluated as a batch of parameter draws.

choice_likelihood

[choice_likelihood]
A choice_likelihood object.

logarithm

[logical(1)]
Return the log-likelihood? If FALSE, the likelihood is returned.

negative

[logical(1)]
Return the negative (log-)likelihood? Useful for minimization routines.

aggregate

[character(1)]
Unit of the returned likelihood:

"occasion" returns one contribution per observed choice occasion,
"decider" returns one joint contribution per decider,
"total" sums the decider contributions.

Value

choice_likelihood() returns an object of class choice_likelihood, which is a list containing the design matrices, choice indices, and identifiers.

compute_choice_likelihood() returns a numeric scalar for aggregate = "total" and a named numeric vector otherwise.

Examples

### compute choice likelihood
data(list = "train_choice")

choice_effects <- choice_effects(
  choice_formula = choice_formula(
    formula = choice ~ price | time,
    error_term = "probit"
  ),
  choice_alternatives = choice_alternatives(
    J = 2,
    alternatives = c("A", "B")
  )
)

choice_data <- choice_data(
  data_frame = train_choice,
  format = "wide",
  column_choice = "choice",
  column_decider = "deciderID",
  column_occasion = "occasionID"
)

likelihood <- choice_likelihood(
  choice_data = choice_data,
  choice_effects = choice_effects
)

choice_parameters <- generate_choice_parameters(
  choice_effects = choice_effects
)

compute_choice_likelihood(
  choice_parameters = choice_parameters,
  choice_likelihood = likelihood,
  logarithm = TRUE
)
#> [1] -141614.3