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("squared", "euclidean"),
alpha = c("random", "fix"),
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; `"squared"` uses squared Euclidean distance (default, often easier for optimization), while `"euclidean"` uses Euclidean distance.
- alpha
Character; `"random"` estimates item-specific alpha values as random effects (default), while `"fix"` estimates a single common alpha.
- 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: 980.68
#> Approx. Log Marginal Likelihood (Laplace): -996.12
#> 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.27114 0.49418 2.30257 4.23970
#> alpha[2] 3.07622 0.49162 2.11266 4.03977
#> alpha[3] 4.63414 0.75250 3.15926 6.10902
#> alpha[4] 2.90268 0.47793 1.96595 3.83941
#> alpha[5] 3.97631 0.62346 2.75434 5.19828
#> alpha[6] 2.90966 0.48232 1.96433 3.85498
#> alpha[7] 3.33538 0.49973 2.35592 4.31483
#> alpha[8] 4.20276 0.65068 2.92746 5.47806
#> alpha[9] 3.36881 0.50718 2.37475 4.36287
#> alpha[10] 3.87143 0.59246 2.71023 5.03263
#>
# Note: MDU models have many parameters, so MCMC sampling might take time.
# \donttest{
# mcmc_mdu <- fit_mdu$sample(sampling = 500, warmup = 500, chains = 2)
# }