prepare_hmnp_data: Prepare inputs for hierarchical multinomial probit estimation

In choicer: Discrete Choice Models for Economic Applications

Prepare inputs for hierarchical multinomial probit estimation

Description

Prepares and validates panel (or cross-sectional) choice data for the hierarchical Bayesian multinomial probit with iid N(0, \sigma^2) utility shocks. The model shares its two-level random-effect structure with prepare_hmnl_data(): respondent-level structural tastes \beta_i \sim N(b, W) over the covariate_cols (normal only — the probit keeps full conjugacy), and a global alternative-level effect \delta_j = z_j'\theta + \xi_j, \xi_j \sim N(0, \sigma_d^2).

Usage

prepare_hmnp_data(
  data,
  id_col,
  alt_col,
  choice_col,
  covariate_cols,
  person_col = NULL,
  alt_covariate_cols = NULL,
  outside_opt_label = NULL,
  cf_residual_col = NULL,
  include_outside_option = TRUE
)

Arguments

data	Data frame containing choice data.
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.
include_outside_option	Logical; if TRUE (default) an implicit outside option with systematic utility 0 is part of every choice set.

Details

The returned structure is identical to prepare_hmnl_data() (both preps share one internal engine), except there is no rc_dist field. Unlike prepare_mnp_data(), utilities are NOT differenced against a base alternative: the iid-shock model works in un-differenced utility space, so unbalanced choice sets are supported and the outside option is implicit (its latent utility is a stochastic N(0, \sigma^2) draw in the kernel, systematic utility 0).

Value

A list of class c("choicer_data_hmnp", "list") with the same components as prepare_hmnl_data() (minus rc_dist).

See Also

prepare_hmnl_data() for the component-by-component description.

Examples

library(data.table)
set.seed(42)
N <- 20; T <- 3; J <- 4
dt <- data.table(
  pid  = rep(1:N, each = T * J),
  task = rep(seq_len(N * T), each = J),
  alt  = rep(1:J, N * T)
)
dt[, `:=`(x1 = rnorm(.N), x2 = runif(.N, -1, 1))]
dt[, choice := 0L]
dt[, choice := if (runif(1) < 0.8) sample(c(1L, rep(0L, J - 1))) else 0L,
   by = task]
input <- prepare_hmnp_data(dt, "task", "alt", "choice", c("x1", "x2"),
                           person_col = "pid")
input$Ti[1:5]
input$alt_mapping

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