klue

Your clue to K. A reusable workflow for specifying latent class multinomial logit (LCMNL) models. Implements the hybrid ML / random-utility framework from Frings (2026), Classes or Continuum? A Pre-Registrable Specification Rule for Latent Class Logit Models.


Install

install.packages("klue",
                 repos = c("https://o-frings.r-universe.dev",
                           "https://cloud.r-project.org"))

(Or from a tarball: install.packages("klue_<version>.tar.gz", repos = NULL, type = "source").)


1. See it work — one line, no setup

library(klue)
klue_demo()

Runs the full workflow on a bundled example dataset (~3 seconds) and prints the BIC/AIC/ICL summary plus class-specific coefficients. Use this once to see what the output looks like before plugging in your own data.

For the full version (C = 1..6 + MMNL benchmark with 500 draws, a few minutes): klue_demo(full = TRUE).


2. Use it on your own data

The package needs to know which column in your data is which. Two common data layouts are supported:

Long format — one row per (respondent × task × alternative)

library(klue)

res <- klue(
  data           = "my_data.csv",          # CSV path or data.frame
  id_col         = "respondent_id",        # who made the choice
  task_col       = "task",                 # which choice task
  alt_col        = "alternative",          # which alternative
  choice_col     = "chosen",               # 0/1 indicator of the picked row
  attribute_cols = c("attr1", "attr2"),    # generic attributes
  price_col      = "price"                 # the price/cost attribute
)

That's all you need. Defaults: estimates C = 1..6, runs MMNL, writes 3 CSVs to output/, returns a results list invisibly.

Wide format — one row per (respondent × task), attributes by alternative

res <- klue(
  data           = my_data,
  format         = "wide",
  id_col         = "ID",
  task_col       = "task",                 # or NULL to auto-number
  choice_col     = "choice",               # integer 1..J of chosen alt
  attribute_cols = list(
    time = c("time_alt1", "time_alt2", "time_alt3"),
    qual = c("qual_alt1", "qual_alt2", "qual_alt3")
  ),
  price_col      = c("cost_alt1", "cost_alt2", "cost_alt3"),
  avail_col      = c("av_alt1", "av_alt2", "av_alt3")   # optional
)

Use NA in an attribute slot to encode a structural zero on that alternative (e.g. some attributes only apply to some alternatives).

Long and wide use the same argument names (attribute_cols, price_col, avail_col); only the type differs (scalar in long, length-J vector or named list in wide).


2b. Simulate data instead (Monte Carlo / methodology testing)

The data-generating process used in the Frings (2026) Monte Carlo study is also exposed:

sim <- klue_simulate(N_per_class = 150, T_tasks = 20, true_K = 2,
                     separation = 1.0, heterogeneity = 0.25, seed = 42)

# Returned: sim$database (canonical wide format) + sim$true_betas, sim$true_class
res <- klue(database = sim$database, C_cands = 1:4)
res$best_C    # should recover 2 here

Variant: klue_simulate(covariates = TRUE) drives class membership by covariates. Full reference: ?klue_simulate.

The Monte Carlo study from Frings (2026) is not part of the package. Its drivers — klue_study() (the 420-condition main simulation plus the robustness analyses, ~12 hours) and the per-component klue_study_main(), klue_study_unbalanced(), klue_study_design(), klue_study_clustering(), etc. — live in studies/klue_studies.R of the reproduction repository: load the package, then source() that file (see its README_REPRODUCE.md).


3. Inspect the results

res$summary          # one row per C: LL, k, BIC, AIC, ICL, ΔBIC, best clustering method
res$class_betas      # class shares and coefficients for the BIC-best model
res$comparison       # MNL (C=1) vs LCMNL (BIC-best) vs MMNL
res$best_C           # the BIC-best number of classes
res$best_lcmnl       # the fit itself (posteriors, betas, etc.)

Three CSVs are written to output/ by default (override with output_dir):


Optional refinements

Argument What it does
price_scaling = 10 Divide price by 10 before estimation (numerical stability).
scalings = list(time = 60, ...) Per-attribute scaling (e.g. seconds → minutes).
avail_col (long) / availability (wide) Drop tasks where some alternative is unavailable.
C_cands = 1:4 Pick a different range of class counts.
run_mmnl = FALSE Skip the independent-normals MMNL benchmark (faster).
run_mmnl_corr = TRUE Additionally estimate a correlated-normals MMNL (full Cholesky covariance). Slower; tests whether heterogeneity is genuinely correlated across attributes.
output_prefix = "myrun" Prefix for the output CSV filenames.
output_dir = "results" Write CSVs somewhere other than output/.
write_csv = FALSE Return results in memory only.

Full reference: ?klue. The package exports the klue_* names only; the paper's Monte Carlo drivers live in ../studies/klue_studies.R.


Availability filtering

The estimation engine assumes every alternative is available in every task. If your data has availability columns, pass them via avail_col (long format) or availability (wide format). The workflow filters to fully-available tasks and reports the drop rate. Partial-availability estimation is not yet supported.

Validation

Five reference applications in Frings (2026) — Rhin-Meuse water-quality DCE, Apollo mode/route choice, Electricity (Train 1998), Swissmetro — reproduce bit-exactly through this workflow against hand-coded baselines. See R/test_klue.R in the source tree for the test.

Citing

If you use klue in published work, please cite the methodology paper, the software itself, and the upstream packages it builds on:

citation("klue")    # returns all five BibTeX entries (auto-updates version)

Acknowledgements

klue wraps the Apollo choice-model estimation engine (Hess & Palma 2019); two of the six starting-value clusterings come from mclust (Scrucca et al. 2016, GMM) and cluster (Maechler et al., PAM). The hybrid workflow and the diagnostics layer are klue's contribution; the underlying MLE machinery and the clustering algorithms are not.


Version history

0.9.3 — simplification (2026-09-17)

This is the rebuilt klue: same exported API as the 0.6.x engine in ../klue/, at roughly 70% of the line count. User-facing documentation: see ../klue/README.md (everything there applies unchanged). Numerical behaviour matched 0.6.x exactly up to 0.9.0; 0.9.1 changes the multistart mechanics (below) — it targets the same optimum, but tie-breaks between equal-LL starts can differ.

0.9.1 — large-N fixes (2026-07-07)

Motivated by a runaway run at N = 6,000: 55+ minutes stuck in the O(N^2) clustering-starts phase with nothing written.

Net effect at N = 6,000 (17 attributes, 4 alternatives, C = 2): ~30 s per multistart on 6 cores, previously unbounded.

0.9.2 — hardening (2026-07-07)

Principle applied throughout: no silent fallbacks — every degraded path now warns, messages, or stops.

What changed internally