Skip to contents

Define choice model parameters

Source: R/choice_parameters.R
choice_parameters.Rd

These functions construct, validate, and transform an object of class choice_parameters, which defines the parameters of a choice model.

  • choice_parameters() constructs a choice_parameters object.

  • generate_choice_parameters() samples parameters at random, see the details on sampling missing choice model parameters.

  • validate_choice_parameters() checks model-specific dimensions.

  • switch_parameter_space() transforms a choice_parameters object between the interpretation and optimization space, see the details on the parameter spaces.

Usage

choice_parameters(
  beta = NULL,
  Omega = NULL,
  Sigma = NULL,
  gamma = NULL,
  weights = NULL
)

generate_choice_parameters(
  choice_effects,
  fixed_parameters = choice_parameters(),
  C = 1L
)

validate_choice_parameters(
  choice_parameters,
  choice_effects,
  allow_missing = FALSE
)

switch_parameter_space(choice_parameters, choice_effects)

Arguments

beta

[numeric(P) | list(C) | NULL]
The coefficient vector for computing the linear-in-parameters systematic utility \(V = X\beta\).

For a latent class model, a list of one coefficient vector per class. Only the effects named in latent_class_effects of the choice_formula may differ between the classes.

Omega

[matrix(nrow = P_r, ncol = P_r) | list(C) | NULL]
The covariance matrix of random effects.

Not used when P_r = 0.

In a latent class model, a list of one covariance matrix per class. Only the block of the random effects with latent class effects may differ between the classes, and it is uncorrelated with the other random effects.

Covariances involving uncorrelated random effects are fixed to zero.

Sigma

[matrix(nrow = J, ncol = J) | numeric(1) | NULL]
Only relevant in the probit model.

For unordered alternatives it is the covariance matrix for the Gaussian error term \(\epsilon = U - V\).

In ordered models it reduces to a single variance term.

gamma

[numeric(J - 1) | NULL]
Vector of strictly increasing threshold parameters required for ordered models.

The first element must equal zero for identification.

weights

[numeric(C) | NULL]
Positive latent class weights.

choice_effects

[choice_effects]
A choice_effects object.

fixed_parameters

[choice_parameters]
A choice_parameters object. Its supplied components are kept fixed. Missing components are completed as described below. A named beta is matched to the effects by name and may contain only some of the effects; the remaining coefficients are drawn.

C

[integer(1)]
Number of latent classes.

choice_parameters

[choice_parameters | numeric()]
A choice_parameters object. For switch_parameter_space() and validate_choice_parameters(), a numeric vector in optimization space is also accepted and converted back to a choice_parameters object.

allow_missing

[logical(1)]
Allow required parameter components to be omitted?

Value

choice_parameters(), generate_choice_parameters(), and validate_choice_parameters() return a choice_parameters list with the elements:

beta

The coefficient vector (if any).

Omega

The random-effect covariance matrix on the underlying normal scale (if any).

Sigma

The error term covariance matrix (or variance in ordered models).

gamma

Threshold parameters for ordered models (if any).

weights

The latent class weights (if any).

switch_parameter_space() returns a named numeric vector when given a choice_parameters object and a choice_parameters object when given a numeric optimization vector.

Sampling missing choice model parameters

generate_choice_parameters() completes required components that are absent from fixed_parameters.

Missing components are generated as follows:

beta

Drawn from a multivariate normal distribution with zero mean and covariance matrix 10 * diag(P), independently for each class for the effects with latent classes and once for the others. A named beta with fewer than P entries fixes the named effects and draws the others.

Omega

Drawn from an Inverse-Wishart distribution with identity scale matrix and degrees of freedom equal to the dimension plus two, independently for each class for the block of the random effects with latent classes and once for the block of the others. Covariances involving uncorrelated random effects are then set to zero.

Sigma

For unordered probit models, the lower right block is drawn from an Inverse-Wishart distribution with J + 1 degrees of freedom and identity scale matrix. The first row and column are fixed to zero and the matrix is scaled so that element \((2, 2)\) equals one. For ordered probit models, Sigma is set to one; logit models do not use Sigma.

gamma

For ordered models with two categories, set to zero. Otherwise, positive increments are drawn as exp(z), where the elements of z are independent standard normal draws, and cumulatively added to the first threshold zero. Unordered models do not use gamma.

weights

Set to equal class probabilities 1 / C.

Parameter spaces

The switch_parameter_space() function transforms a choice_parameters object between the interpretation and optimization space.

  • The interpretation space is a list of (not necessarily identified) parameters that can be interpreted.

  • The optimization space is a numeric vector of identified parameters that can be optimized:

    • beta is not transformed

    • Omega is represented by its vectorized unique Cholesky factor; elements involving uncorrelated random effects are omitted

    • for unordered probit models, Sigma is represented through utility differences relative to the first alternative, with the first variance fixed to one, and transformed to a vectorized unique Cholesky factor

    • for ordered probit models, the positive scalar Sigma is log-transformed

    • the first ordered threshold is fixed to zero and omitted; logarithms of the remaining positive threshold increments are used

    • in a latent class model, the coefficients and Cholesky elements of the effects with latent classes are concatenated in class order and followed by those of the other effects, which appear once; C - 1 log weight ratios use the first class as reference

Examples

### generate choice parameters at random
J <- 3
choice_effects <- choice_effects(
  choice_formula = choice_formula(
    formula = choice ~ x | y, error_term = "probit",
    random_effects = c("x" = "cn")
  ),
  choice_alternatives = choice_alternatives(J = J)
)
(parameters <- generate_choice_parameters(
  choice_effects = choice_effects,
  fixed_parameters = choice_parameters(
    Sigma = diag(c(0, rep(1, J - 1))) # scale and level normalization
  )
))
#> $beta
#>        y_B        y_C      ASC_B      ASC_C          x 
#>  0.4069475 -4.8479786  0.6399206 -2.2690565  1.1437793 
#> 
#> $Omega
#>           x
#> x 0.1731118
#> 
#> $Sigma
#>   A B C
#> A 0 0 0
#> B 0 1 0
#> C 0 0 1
#> 
#> attr(,"class")
#> [1] "choice_parameters" "list"             

### switch between interpretation and optimization spaces
(optimization_parameters <- switch_parameter_space(
  choice_parameters = parameters,
  choice_effects = choice_effects
))
#>     beta_1     beta_2     beta_3     beta_4     beta_5        o_1        l_2 
#>  0.4069475 -4.8479786  0.6399206 -2.2690565  1.1437793  0.4160670  0.0000000 
#>        l_3 
#>  1.0000000 
switch_parameter_space(
  choice_parameters = optimization_parameters,
  choice_effects = choice_effects
)
#> $beta
#>        y_B        y_C      ASC_B      ASC_C          x 
#>  0.4069475 -4.8479786  0.6399206 -2.2690565  1.1437793 
#> 
#> $Omega
#>           x
#> x 0.1731118
#> 
#> $Sigma
#>   A B C
#> A 0 0 0
#> B 0 1 0
#> C 0 0 1
#> 
#> attr(,"class")
#> [1] "choice_parameters" "list"