simulate_hmnl_data: Simulate hierarchical multinomial logit data

In choicer: Discrete Choice Models for Economic Applications

Simulate hierarchical multinomial logit data

Description

Generates synthetic panel choice data from the hierarchical (random coefficients + alternative-level random effects) logit DGP: respondents ⁠i = 1..N⁠ face T choice situations each, with utilities

U_{ijt} = x_{ijt}'\gamma_i + \delta_j + \epsilon_{ijt}, \qquad U_{iot} = \epsilon_{iot},

i.i.d. Gumbel shocks (including a shock on the outside option, whose systematic utility is 0), \beta_i \sim N(\beta, W) with \gamma_{ik} = \beta_{ik} or \exp(\beta_{ik}) per rc_dist, and \delta_j = z_j'\theta + \xi_j with \xi_j \sim N(0, \sigma_d^2). Covariates are Uniform(-1, 1); the alternative-level covariates ⁠z*⁠ are constant within each alternative.

Usage

simulate_hmnl_data(
  N = 500,
  T = 10,
  J = 4,
  beta = c(0.8, -0.6),
  W = NULL,
  theta = c(0.5, -0.4),
  sigma_d = 0.5,
  Z = NULL,
  rc_dist = NULL,
  include_outside = TRUE,
  seed = 123,
  vary_choice_set = FALSE
)

Arguments

N	Number of respondents.
T	Number of choice situations per respondent.
J	Number of inside alternatives.
beta	Population means of the structural random coefficients (length K_x = length(beta); chain scale for log-normal coordinates).
W	Covariance of the random coefficients (K_x x K_x). Defaults to diag(0.5, K_x).
theta	Mean-function coefficients for \delta_j = z_j'\theta + \xi_j; the first entry is the intercept, entries ⁠2..P⁠ load on the alternative-level covariates.
sigma_d	Standard deviation of the alternative-level effects \xi_j.
Z	Optional ⁠J x (length(theta) - 1)⁠ matrix of alternative-level covariates (excluding the intercept). Default NULL draws them Uniform(-1, 1).
rc_dist	Integer vector (length K_x): 0L for normal, 1L for log-normal coordinates. Default NULL is all-normal.
include_outside	Logical; if TRUE (default) every choice set also contains an outside option with systematic utility 0 and its own Gumbel shock. The outside good is implicit in the returned data (matching the prepare_hmnl_data() convention): no physical row is emitted, and a choice situation the outside option wins has an all-zeros choice column.
seed	Random seed (NULL skips set.seed()).
vary_choice_set	Logical; if TRUE choice-set size is sampled uniformly from 2:J per task. Default FALSE.

Details

Log-normal coordinates are reported on the chain (log) scale in true_params$beta — the scale on which the estimator's hierarchy operates — while entering utility as exp(beta_ik).

Value

A choicer_sim object. true_params contains beta, W, theta, sigma_d, the realized delta and xi vectors, the full mean-function design Z (intercept first), and rc_dist.

Examples

sim <- simulate_hmnl_data(N = 100, T = 4, J = 4, seed = 123)
print(sim)
sim$true_params$delta

choicer documentation built on Sept. 5, 2026, 1:07 a.m.