run_hmnprobit: Fit a hierarchical Bayesian multinomial probit (HMNP)

In choicer: Discrete Choice Models for Economic Applications

Fit a hierarchical Bayesian multinomial probit (HMNP)

Description

Runs the fully conjugate Albert-Chib Gibbs sampler for the hierarchical multinomial probit with iid normal utility shocks in un-differenced utility space:

U_{ijt} = x_{ijt}'\beta_i + \delta_j + \epsilon_{ijt}, \qquad U_{iot} = \epsilon_{iot}, \qquad \epsilon \sim N(0, \sigma^2),

choice by argmax within the task including the stochastic implicit outside option, \beta_i \sim N(b, W) (normal coordinates only — log-normal would break conjugacy), and \delta_j = z_j'\theta + \xi_j, \xi_j \sim N(0, \sigma_d^2).

Usage

run_hmnprobit(
  data = NULL,
  id_col = NULL,
  alt_col = NULL,
  choice_col = NULL,
  covariate_cols = NULL,
  person_col = NULL,
  alt_covariate_cols = NULL,
  outside_opt_label = NULL,
  cf_residual_col = NULL,
  input_data = NULL,
  include_outside_option = TRUE,
  prior = list(),
  mcmc = list(),
  chains = 1,
  keep_beta_i = c("means", "draws", "none"),
  keep_data = TRUE
)

Arguments

data	Data frame (convenience pathway). Supply either data (with the column names) or input_data, not both.
id_col	Name of the column identifying choice situations (tasks). Task ids only need to be unique within a respondent.
alt_col	Name of the column identifying alternatives.
choice_col	Name of the column indicating the chosen alternative (1 = chosen, 0 = not chosen).
covariate_cols	Vector of names of structural covariate columns (the random-coefficient dimensions).
person_col	Name of the respondent column grouping choice situations. NULL (default) makes each choice situation its own respondent.
alt_covariate_cols	Names of alternative-level covariate columns (constant within each alternative) forming the \delta mean function. NULL (default) gives an intercept-only design (P = 1).
outside_opt_label	Label of physical outside-option rows, removed when include_outside_option = TRUE (the outside good is implicit).
cf_residual_col	Name of a first-stage residual column (control function for an endogenous covariate), appended to X. Default NULL.
input_data	A choicer_data_hmnp object from prepare_hmnp_data().
include_outside_option	Logical; if TRUE (default) an implicit outside option with systematic utility 0 is part of every choice set.
prior	As in run_hmnlogit(), plus a0 (3) and s0 (3), the inverse-gamma shape/scale on the non-identified \sigma^2.
mcmc	Named list overriding MCMC defaults: R (10000), burn (R %/% 5), thin (1), seed (drawn via sample.int() so set.seed() governs), trace (0). No proposal-scale settings: the sampler is fully conjugate, with no Metropolis steps.
chains	Number of independent chains (seeds offset by 1, run sequentially). Chain 1 provides the reported draws; all chains feed the rank-normalized split-R-hat table and the retained chains field (all per-chain b/w_vech/delta/theta/sigma_d2/loglik draws, consumed by ess(), mcse(), and traceplot()).
keep_beta_i	"means" (default) stores posterior means/SDs of the individual-level \beta_i; "draws" additionally stores the full (K, N, R_keep) draw cube (memory-guarded, budgeted per chain); "none" stores neither.
keep_data	Logical; keep the prepared data on the fit (default TRUE, needed by post-estimation methods).

Details

Identification. The probit likelihood is invariant to a common rescaling of utilities and \sigma, so the chain runs on the non-identified parameterization (free \sigma^2, better mixing via parameter expansion) and every kept draw is normalized by the matching power of the CURRENT \sigma: reported b/\sigma, W/\sigma^2, \delta/\sigma, \theta/\sigma, \sigma_d^2/\sigma^2. Raw chains are kept in ⁠draws$*_raw⁠. The outside option anchors the location of \delta exactly as in run_hmnlogit().

For beta_i draws at very large scale beyond the memory guard's threshold, a future disk-streaming path (writing each kept slice to disk instead of retaining it in memory) is on the roadmap but not built in this phase; users needing per-respondent draws at that scale should reduce R, reduce chains, or use keep_beta_i = "means".

Value

A choicer_hmnp object (classed c("choicer_hmnp", "choicer_hb")); the same layout as run_hmnlogit()'s return, with all reported summaries on the identified scale, raw chains in ⁠draws$*_raw⁠, the non-identified draws$sigma2 trace, and all chains' retained draws (identified scale) in chains.

See Also

prepare_hmnp_data(), simulate_hmnp_data(), run_hmnlogit(), ess(), mcse(), traceplot()

Examples

sim <- simulate_hmnp_data(N = 100, T = 3, J = 4, seed = 42)
fit <- suppressWarnings(run_hmnprobit(sim$data, "task", "alt", "choice", c("x1", "x2"),
                     person_col = "pid", alt_covariate_cols = "z1",
                     mcmc = list(R = 500, burn = 200)))
summary(fit)

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