BLP contraction mapping for mixed logit model

Usage

# S3 method for class 'choicer_mxl'
blp(
  object,
  target_shares,
  delta_init = NULL,
  tol = 1e-08,
  max_iter = 1000,
  keep_draws_bytes = 2^32,
  ...
)

Arguments

object: A choicer_mxl object fitted with keep_data = TRUE.
target_shares: Numeric vector of target market shares. Length J_inside when no outside option, or J_inside + 1 (with the outside option's share at index 1) when include_outside_option = TRUE.
delta_init: Initial guess for delta (ASC) values. If NULL, uses the estimated ASCs from the fitted model.
tol: Convergence tolerance (default 1e-8).
max_iter: Maximum iterations (default 1000).
keep_draws_bytes: Most memory, in bytes, that the contraction may use to keep the draws across its iterations; it does not change the returned delta. When the draws are formed on the fly and those of all \(N\) choice situations take at most this much (\(8 K_w S N\) bytes for \(K_w\) random coefficients and \(S\) draws), the first evaluation of the shares forms them and the later iterations reuse them, which saves up to about a quarter of each iteration on large designs; above it, every iteration forms them again. The default, 2^32 (4 GiB), covers up to about 1.8 million choice situations at \(K_w = 3\) and \(S = 100\); 0 never keeps the draws, and Inf keeps them whenever they are formed on the fly and can be allocated. The memory is taken per call, on top of the fit's data (parallel workers each take their own). Where memory is committed only when used (Linux, macOS, and containers or batch jobs with memory limits), a budget above the memory actually free can end the R session rather than fall back: lower it, or use 0, when memory is tight.
...: Additional arguments (ignored).

Value

Converged delta (ASC) vector.

Details

The contraction integrates each choice situation over the same draws as predict() (for a cross-sectional fit, the estimation draws; a panel fit's estimation draws are per decision maker), formed on the fly, in parallel, and kept across iterations within keep_draws_bytes. With stored draws (draws = "store") they are the points of the cube get_halton_normals would build, formed without it; with more than 128 random coefficients, the cube itself, read at every iteration (and nothing more is kept).

Examples

# \donttest{
library(data.table)
set.seed(42)
N <- 50; J <- 3
dt <- data.table(id = rep(1:N, each = J), alt = rep(1:J, N))
dt[, `:=`(x1 = rnorm(.N), w1 = rnorm(.N))]
#>         id   alt         x1          w1
#>      <int> <int>      <num>       <num>
#>   1:     1     1  1.3709584 -0.04069848
#>   2:     1     2 -0.5646982 -1.55154482
#>   3:     1     3  0.3631284  1.16716955
#>   4:     2     1  0.6328626 -0.27364570
#>   5:     2     2  0.4042683 -0.46784532
#>  ---                                   
#> 146:    49     2  1.1133860 -0.47733551
#> 147:    49     3 -0.4809928 -0.16626149
#> 148:    50     1 -0.4331690  0.86256338
#> 149:    50     2  0.6968626  0.09734049
#> 150:    50     3 -1.0563684 -1.62561674
dt[, choice := 0L]
#>         id   alt         x1          w1 choice
#>      <int> <int>      <num>       <num>  <int>
#>   1:     1     1  1.3709584 -0.04069848      0
#>   2:     1     2 -0.5646982 -1.55154482      0
#>   3:     1     3  0.3631284  1.16716955      0
#>   4:     2     1  0.6328626 -0.27364570      0
#>   5:     2     2  0.4042683 -0.46784532      0
#>  ---                                          
#> 146:    49     2  1.1133860 -0.47733551      0
#> 147:    49     3 -0.4809928 -0.16626149      0
#> 148:    50     1 -0.4331690  0.86256338      0
#> 149:    50     2  0.6968626  0.09734049      0
#> 150:    50     3 -1.0563684 -1.62561674      0
dt[, choice := sample(c(1L, rep(0L, J - 1))), by = id]
#>         id   alt         x1          w1 choice
#>      <int> <int>      <num>       <num>  <int>
#>   1:     1     1  1.3709584 -0.04069848      0
#>   2:     1     2 -0.5646982 -1.55154482      0
#>   3:     1     3  0.3631284  1.16716955      1
#>   4:     2     1  0.6328626 -0.27364570      0
#>   5:     2     2  0.4042683 -0.46784532      0
#>  ---                                          
#> 146:    49     2  1.1133860 -0.47733551      0
#> 147:    49     3 -0.4809928 -0.16626149      0
#> 148:    50     1 -0.4331690  0.86256338      1
#> 149:    50     2  0.6968626  0.09734049      0
#> 150:    50     3 -1.0563684 -1.62561674      0
fit <- run_mxlogit(
  data = dt, id_col = "id", alt_col = "alt", choice_col = "choice",
  covariate_cols = "x1", random_var_cols = "w1", S = 50L
)
#> Optimization run time 0h:0m:0s
blp(fit, target_shares = rep(1/J, J))
#>             [,1]
#> [1,]  0.00000000
#> [2,] -0.01837653
#> [3,] -0.04093113
# }