nl_blp_contraction: BLP95 contraction mapping for the Nested Logit model

In choicer: Discrete Choice Models for Economic Applications

BLP95 contraction mapping for the Nested Logit model

Description

Damped iterative fixed point recovering delta given target shares, using the NL probability structure. damping = 1 reproduces the plain BLP update.

Usage

nl_blp_contraction(
  delta,
  target_shares,
  X,
  beta,
  lambda,
  alt_idx,
  nest_idx,
  M,
  weights,
  include_outside_option = FALSE,
  damping = 1,
  tol = 1e-08,
  max_iter = 1000L
)

Arguments

delta	J x 1 vector with initial guess for deltas (ASCs).
target_shares	vector with target shares (outside-option share first when present).
X	sum(M) x K design matrix with covariates.
beta	K x 1 vector with fixed coefficients.
lambda	full nest dissimilarity vector of length n_nests (singletons = 1).
alt_idx	sum(M) x 1 vector with indices of alternatives; 1-based indexing.
nest_idx	J x 1 vector with nest indices for each alternative; 1-based indexing.
M	N x 1 vector with number of alternatives for each individual.
weights	N x 1 vector with weights for each observation.
include_outside_option	whether to include outside option normalized to V=0, lambda=1.
damping	damping factor for the update (default 1.0 = plain BLP).
tol	convergence tolerance.
max_iter	maximum number of iterations.

Value

vector with contraction's delta (ASCs) output.

Examples

library(data.table)
set.seed(42)
N <- 50; J <- 4
dt <- data.table(id = rep(1:N, each = J), alt = rep(1:J, N))
dt[, `:=`(x1 = rnorm(.N), x2 = rnorm(.N))]
dt[, nest := ifelse(alt <= 2, "A", "B")]
dt[, choice := 0L]
dt[, choice := sample(c(1L, rep(0L, J - 1))), by = id]
fit <- run_nestlogit(dt, "id", "alt", "choice", c("x1", "x2"), "nest")
beta <- coef(fit)[fit$param_map$beta]
lambda <- rep(1, length(unique(fit$data$nest_idx)))
lambda[as.integer(names(which(table(fit$data$nest_idx) > 1)))] <-
  coef(fit)[fit$param_map$lambda]
delta <- nl_blp_contraction(rep(0, J), rep(1/J, J), fit$data$X, beta, lambda,
  fit$data$alt_idx, fit$data$nest_idx, fit$data$M, fit$data$weights)
delta

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