--- title: "Explanatory Rasch models" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Explanatory Rasch models} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") library(rasch) ``` The linear logistic test model (LLTM; Fischer, 1973) explains dichotomous item locations using observed item characteristics. The linear partial credit model (LPCM; Fischer and Ponocny, 1994) extends the same formulation to polytomous thresholds. Both retain the common discrimination and conditional Rasch structure. For category \(k\) of item \(i\), \[ \log\frac{P(X_{ni}=k)}{P(X_{ni}=k-1)} =\theta_n-\delta_{ik}, \qquad \delta_{ik}=\mathbf z_{ik}^{\mathsf T}\gamma . \] The vector \(\mathbf z_{ik}\) contains the nominated item or threshold characteristics. An interaction permits the effect of one characteristic to differ according to another. The scale origin is fixed at mean item location zero, as in `rasch()`; the formula intercept is therefore absorbed by the origin constraint. ## Item predictors Item-level metadata contain one row per item. This example explains eight dichotomous item locations by the operation required and the response format. ```{r lltm} set.seed(1) item_design <- data.frame( item = paste0("I", 1:8), operation = rep(c("recall", "inference"), each = 4), format = rep(c("selected", "constructed"), 4) ) difficulty <- 0.8 * (item_design$operation == "inference") + 0.4 * (item_design$format == "constructed") theta <- rnorm(500) X <- sapply(difficulty, function(delta) rbinom(length(theta), 1, plogis(theta - delta))) colnames(X) <- item_design$item fit <- rasch_explanatory( X, predictors = item_design, formula = ~ operation + format, level = "item" ) fit$est$coefficients ``` Predictors may be continuous, categorical or ordinal. Numeric vectors are continuous and unordered factors are categorical. An ordered factor is scored with successive contrasts: each coefficient is the change between two adjacent levels in the declared order. Character vectors are converted to unordered factors; the first factor level is the reference category. For example: ```{r predictor-types, eval=FALSE} item_design$demand <- as.numeric(item_design$demand) item_design$format <- factor(item_design$format) item_design$complexity <- ordered( item_design$complexity, levels = c("low", "moderate", "high") ) ``` This coding uses the order without assuming equal spacing and does not fit polynomial contrasts. Use an unordered factor for comparisons with a single reference category, or a numeric predictor when the spacing has a substantive scale. Selected interactions can be added, for example `~ demand + format + complexity + format:complexity`. ## Threshold predictors For an LPCM, item metadata may still be supplied once per item. The reserved factor `threshold` identifies the within-item threshold and can be used in the formula: ```{r lpcm-form, eval=FALSE} lpcm <- rasch_explanatory( responses, predictors = item_design, formula = ~ operation + format + threshold + format:threshold, level = "item" ) ``` Use `level = "threshold"` when a predictor varies within an item. The metadata must then contain `item`, `threshold`, and one row for every observed item threshold. `threshold_number` is also available as an integer predictor. ## Comparing the restriction with a free calibration `rasch_explanatory()` retains a free partial credit calibration of the same responses. `explanatory_test()` compares it with the active explanatory model. Pairwise conditional estimation produces a composite likelihood, so the reported inferential result is the first-order Kent-adjusted chi-square rather than an ordinary likelihood-ratio test. The same table reports calibration \(R^2\), the proportion of variation in the free threshold calibration reproduced by the explanatory thresholds. Comparative judgement uses the corresponding free object calibration. ```{r comparison} explanatory_test(fit) ``` A non-significant result does not establish that the explanatory structure is true. It indicates that the free calibration has not detected a departure at the available precision. Coefficients should be interpreted together with their standard errors, item fit, targeting, and the study design. ## Fixed departures `rasch_explanatory()` begins with the exact explanatory restriction. Its error formulation uses nominated fixed departures rather than a random item effect, so it does not introduce an item population distribution. An explanatory model can be too restrictive for a small number of items. `explanatory_diagnostics()` adds each available departure separately and adjusts the complete family of probabilities by Holm's method. ```{r diagnostics} departures <- explanatory_diagnostics(fit) head(departures) ``` An item-location departure moves all thresholds of an item together. A threshold-structure departure changes their relative locations and is available only for polytomous items. A departure should be accepted on substantive grounds, not selected solely because it has the smallest probability. ```{r relax, eval=FALSE} fit <- relax_explanatory(fit, item = "I4", component = "location") ``` The refit remains a fixed-effects Rasch model: no item distribution or random effect is introduced. Item locations, person measures, residuals, fit statistics and subsequent analyses are all recomputed. Item deletion, DIF splitting and superitem construction retain the explanatory structure and add the required fixed departures for changed items. Response-dependence resolution does the same for its resolved item copies. With keyed multiple-choice data, unchanged and split items retain their raw responses for distractor analysis. The same workflow is available under **Explanatory** in the Shiny application. Predictor type is selected explicitly in the application; ordinal predictors also require their level order. The project file records the predictor metadata, formula and accepted departures, and the displayed R code reproduces the analysis. ## Comparative judgement `btl_explanatory()` constrains object rather than item locations. Predictor metadata contain one row per object and an `object` column. The formulation is \[ \log\frac{P(a\succ b)}{P(b\succ a)} =\beta_a-\beta_b, \qquad \beta_i=\mathbf z_i^{\mathsf T}\gamma . \] ```{r cj, eval=FALSE} cj <- btl_explanatory( comparisons, predictors = object_design, formula = ~ domain + format + domain:format, object_a = "object_a", object_b = "object_b", winner = "winner", judge = "judge" ) explanatory_test(cj) explanatory_diagnostics(cj) ``` An ordered `response` may be supplied instead of `winner`. Its symmetric response thresholds are estimated jointly with the explanatory object effects. Judge-clustered covariance and its existing availability rules continue to apply. `relax_btl_explanatory()` adds a nominated fixed object-location departure and repeats the complete fit. ## Validation Regression checks compare the LLTM and LPCM calibrations with `eRm`. In the simulation study, coefficient bias was at most 0.005 logits, empirical standard deviations divided by mean reported standard errors ranged from 0.99 to 1.03, and 95% coverage ranged from 0.938 to 0.955 across LLTM, LPCM, dichotomous comparative judgement, ordered comparative judgement and judge-clustered comparative judgement conditions. Kent-adjusted null rejection ranged from 4.2% to 6.0% (1,000 replicates per condition). Holm familywise error for fixed-departure diagnostics was 4.3% to 4.7%, with 98.3% to 100% power for a planted 0.8-logit departure (300 replicates per condition). A further 1,000-replicate study covered mixed maximum scores and four-category LPCMs at 300 to 2,000 persons. SE ratios were 0.993 to 1.026, coverage was 0.942 to 0.954, Kent-adjusted null rejection was 4.3% to 5.8%, and mean calibration \(R^2\) was 0.872 to 0.994. The unscaled probability rejected 98.6% to 100% and is therefore returned only as `p_naive`. No fit in these four conditions was refused or failed to converge. Scripts and full result tables are under `tools/simval/` in the source repository. ## References Fischer, G. H. (1973). The linear logistic test model as an instrument in educational research. *Acta Psychologica*, 37(6), 359--374. Fischer, G. H., and Ponocny, I. (1994). An extension of the partial credit model with an application to the measurement of change. *Psychometrika*, 59(2), 177--192. Mair, P., and Hatzinger, R. (2007). Extended Rasch modeling: The eRm package for the application of IRT models in R. *Journal of Statistical Software*, 20(9), 1--20. doi:10.18637/jss.v020.i09.