Fits a multidimensional unfolding model for preference/rating data. Rows are persons or observations and columns are stimuli/items. The model represents both row scores (`theta`) and item locations (`delta`) in a shared D-dimensional space.
Usage
rtmb_mdu(
data,
ndim = 2,
distance = c("euclidean", "squared"),
alpha = c("random", "fix"),
lambda = c("fix", "random"),
method = c("rating", "Best", "Best-Worst", "MDS"),
sets = NULL,
prior = prior_flat(),
y_range = NULL,
init = NULL,
fixed = NULL,
view = NULL,
distance_eps = 1e-04,
missing = c("listwise", "fiml"),
WAIC = FALSE
)Arguments
- data
Numeric matrix or data frame (N rows x M items) for `method = "rating"`. For choice methods, a list containing `Best` and, for `method = "Best-Worst"`, `Worst`. For `method = "Best-Worst"`, a single matrix/data frame is treated as pre-coded `Y_dif` pair indices.
- ndim
Number of unfolding dimensions.
- distance
Character; `"euclidean"` uses Euclidean distance (default), while `"squared"` uses squared Euclidean distance.
- alpha
Character; `"random"` estimates item-specific alpha values as random effects (default), while `"fix"` estimates a single common alpha.
- lambda
Character; for choice methods, `"fix"` estimates a common inverse-temperature parameter (default), while `"random"` estimates person-specific inverse-temperature parameters with a log-normal hierarchy.
- method
Character; `"rating"` for continuous ratings, `"Best"` for best-only choice tasks, `"Best-Worst"` for best-worst choice tasks, or `"MDS"` for fitting a multidimensional scaling model to a distance matrix.
- sets
Matrix or data frame of presented item sets (P tasks x C items) for choice methods.
- prior
Prior configuration: `prior_flat()`, `prior_normal()`, or `prior_weak()`. `prior_flat()` creates a maximum-likelihood model suitable for `classic()`. The latent coordinates `delta` and `theta` are always treated as random effects with normal scale priors, similarly to IRT ability parameters.
- y_range
Optional response range for `method = "rating"`. If supplied with the default flat prior, `prior_weak()` is used. For choice methods (`"Best"` and `"Best-Worst"`), `prior_weak()` behaves like `prior_normal()` because there is no observed rating scale.
- init
Optional named list of initial values.
- fixed
Optional named list of parameter values to fix.
- view
Character vector of parameter names to prioritize in summaries.
- distance_eps
Small positive constant added to the distance.
- missing
Missing value handling strategy: "listwise" (default) or "fiml" (Full Information Maximum Likelihood).
- WAIC
Logical; if TRUE, add pointwise `log_lik` to the generate block for WAIC.
Examples
# Simulate rating data for Multidimensional Unfolding (MDU)
set.seed(123)
N <- 50 # Number of persons
M <- 10 # Number of items
D <- 2 # Number of dimensions
# True person and item coordinates in a 2D space
theta <- matrix(rnorm(N * D), N, D)
delta <- matrix(rnorm(M * D), M, D)
# Generate distance-like ratings (smaller means more preferred)
Y <- matrix(NA, N, M)
for(i in 1:N) {
for(j in 1:M) {
Y[i, j] <- sum((theta[i,] - delta[j,])^2) + rnorm(1, 0, 0.5)
}
}
# Fit a 2-dimensional MDU model
fit_mdu <- rtmb_mdu(Y, ndim = 2, distance = "squared", method = "rating")
#> Pre-checking model code...
#> Checking RTMB setup...
# MAP estimation
map_mdu <- fit_mdu$optimize()
#> Starting RTMB optimization...
map_mdu$summary()
#>
#> Call:
#> MAP Estimation via RTMB
#>
#> Negative Log-Posterior: 977.95
#> Approx. Log Marginal Likelihood (Laplace): -993.42
#> Note: Random effects are stored in $random_effects (use ranef = TRUE to show them)
#>
#> Point Estimates and 95% Wald CI:
#> variable Estimate Std. Error Lower 95% Upper 95%
#> alpha[1] 3.24149 0.48954 2.28202 4.20097
#> alpha[2] 3.07680 0.48789 2.12055 4.03304
#> alpha[3] 4.58333 0.74269 3.12768 6.03898
#> alpha[4] 2.89562 0.47457 1.96548 3.82575
#> alpha[5] 3.94807 0.61796 2.73689 5.15926
#> alpha[6] 2.90950 0.47861 1.97145 3.84756
#> alpha[7] 3.31641 0.49573 2.34480 4.28801
#> alpha[8] 4.16539 0.64349 2.90418 5.42660
#> alpha[9] 3.34095 0.50248 2.35611 4.32579
#> alpha[10] 3.86744 0.59089 2.70931 5.02557
#>
# Note: MDU models have many parameters, so MCMC sampling might take time.
# \donttest{
# mcmc_mdu <- fit_mdu$sample(sampling = 500, warmup = 500, chains = 2)
# }