Score future or partially observed units under a fixed MML calibration

Usage

predict_mfrm_units(
  fit,
  new_data,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  interval_level = 0.95,
  n_draws = 0,
  seed = NULL
)

Arguments

fit: Output from fit_mfrm() with method = "MML".
new_data: Long-format data for the future or partially observed units to be scored.
person: Optional person column in new_data. Defaults to the person column recorded in fit.
facets: Optional facet-column mapping for new_data. Supply either an unnamed character vector in the calibrated facet order or a named vector whose names are the calibrated facet names and whose values are the column names in new_data.
score: Optional score column in new_data. Defaults to the score column recorded in fit.
weight: Optional weight column in new_data. Defaults to the weight column recorded in fit, if any.
interval_level: Posterior interval level returned in Lower/Upper.
n_draws: Optional number of quadrature-grid posterior draws to return per scored person. Use 0 to skip draws.
seed: Optional seed for reproducible posterior draws.

Value

An object of class mfrm_unit_prediction with components:

estimates: posterior summaries by person
draws: optional quadrature-grid posterior draws
audit: row-level preparation audit for new_data
input_data: cleaned canonical scoring rows retained from new_data
settings: scoring settings
notes: interpretation notes

Details

predict_mfrm_units() is the individual-unit companion to predict_mfrm_population(). It uses a fixed MML calibration and scores new or partially observed persons via Expected A Posteriori (EAP) summaries on the fitted quadrature grid.

This is appropriate for questions such as:

what posterior location/uncertainty do these partially observed new respondents have under the existing calibration?
how uncertain are those scores, given the observed response pattern?

All non-person facet levels in new_data must already exist in the fitted calibration. The function does not recalibrate the model, update facet estimates, or treat overlapping person IDs as the same latent units from the training data. Person IDs in new_data are treated as labels for the rows being scored.

When n_draws > 0, the returned draws component contains discrete quadrature-grid posterior draws that can be used as approximate plausible values under the fixed calibration. They should be interpreted as posterior uncertainty summaries, not as deterministic future truth values.

Interpreting output

estimates contains posterior EAP summaries for each person in new_data.
Lower and Upper are quadrature-grid posterior interval bounds at the requested interval_level.
SD is posterior uncertainty under the fixed MML calibration.
draws, when requested, contains approximate plausible values on the fitted quadrature grid.

What this does not justify

This helper does not update the original calibration, estimate new non-person facet levels, or produce deterministic future person true values. It scores new response patterns under a fixed calibration model.

References

The posterior summaries follow the usual MML/EAP scoring framework used in item response modeling under fixed calibrated parameters (for example Bock & Aitkin, 1981). Optional posterior draws are exposed as quadrature-grid plausible-value-style summaries in the spirit of Mislevy (1991), but here they are offered as practical uncertainty summaries for fixed-calibration many-facet scoring rather than as a direct implementation of a published many-facet plausible-values procedure.

Bock, R. D., & Aitkin, M. (1981). Marginal maximum likelihood estimation of item parameters: Application of an EM algorithm. Psychometrika, 46(4), 443-459.
Mislevy, R. J. (1991). Randomization-based inference about latent variables from complex samples. Psychometrika, 56(2), 177-196.

Examples

toy <- load_mfrmr_data("example_core")
keep_people <- unique(toy$Person)[1:18]
toy_fit <- suppressWarnings(
  fit_mfrm(
    toy[toy$Person %in% keep_people, , drop = FALSE],
    "Person", c("Rater", "Criterion"), "Score",
    method = "MML",
    quad_points = 5,
    maxit = 15
  )
)
raters <- unique(toy$Rater)[1:2]
criteria <- unique(toy$Criterion)[1:2]
new_units <- data.frame(
  Person = c("NEW01", "NEW01", "NEW02", "NEW02"),
  Rater = c(raters[1], raters[2], raters[1], raters[2]),
  Criterion = c(criteria[1], criteria[2], criteria[1], criteria[2]),
  Score = c(2, 3, 2, 4)
)
pred_units <- predict_mfrm_units(toy_fit, new_units, n_draws = 0)
summary(pred_units)$estimates[, c("Person", "Estimate", "Lower", "Upper")]
#> # A tibble: 2 × 4
#>   Person Estimate Lower Upper
#>   <chr>     <dbl> <dbl> <dbl>
#> 1 NEW01    -0.149 -1.36  1.36
#> 2 NEW02     0.279 -1.36  1.36