predict_mfrm_units: Score future or partially observed units under a fixed MML...

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Score future or partially observed units under a fixed MML calibration

Description

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.

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.

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

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.

See Also

predict_mfrm_population(), fit_mfrm(), summary.mfrm_unit_prediction

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")]

mfrmr documentation built on March 31, 2026, 1:06 a.m.