% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-prediction.R
\name{sample_mfrm_plausible_values}
\alias{sample_mfrm_plausible_values}
\title{Sample approximate plausible values under fitted posterior scoring}
\usage{
sample_mfrm_plausible_values(
  fit,
  new_data,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  person_data = NULL,
  person_id = NULL,
  population_policy = c("error", "omit"),
  n_draws = 5,
  interval_level = 0.95,
  seed = NULL
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} estimated with \code{method = "MML"} or
\code{method = "JML"}.}

\item{new_data}{Long-format data for the future or partially observed units
to be scored.}

\item{person}{Optional person column in \code{new_data}. Defaults to the person
column recorded in \code{fit}.}

\item{facets}{Optional facet-column mapping for \code{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 \code{new_data}.}

\item{score}{Optional score column in \code{new_data}. Defaults to the score
column recorded in \code{fit}.}

\item{weight}{Optional weight column in \code{new_data}. Defaults to the weight
column recorded in \code{fit}, if any.}

\item{person_data}{Optional one-row-per-person data.frame with the
background variables required by a latent-regression fit. Ignored for
ordinary fixed-calibration scoring. Intercept-only latent-regression fits
can reconstruct the minimal scored-person table internally. This is the
scoring-time table for \code{new_data}, not the fit object's replay/export
provenance table. For categorical background variables, supply values on
the same coding scale used at fit time; the fitted factor levels and
contrasts are reused when building the scoring design matrix.}

\item{person_id}{Optional person-ID column in \code{person_data}.}

\item{population_policy}{How missing background data are handled when
\code{fit} uses the latent-regression branch. \code{"error"} (default) requires
complete person-level covariates; \code{"omit"} drops scored persons lacking
complete covariates and records that omission in \code{population_review}.}

\item{n_draws}{Number of posterior draws per person. Must be a positive
integer.}

\item{interval_level}{Posterior interval level passed to
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}} for the accompanying EAP summary table.}

\item{seed}{Optional seed for reproducible posterior draws.}
}
\value{
An object of class \code{mfrm_plausible_values} with components:
\itemize{
\item \code{values}: one row per person per draw
\item \code{estimates}: companion posterior EAP summaries
\item \code{row_review}: row-preparation review
\item \code{population_review}: optional person-level omission review for
latent-regression scoring
\item \code{input_data}: cleaned canonical scoring rows retained from \code{new_data}
\item \code{person_data}: cleaned or supplied person-level background data used for
latent-regression scoring; \code{NULL} otherwise
\item \code{settings}: scoring settings
\item \code{notes}: interpretation notes
}
}
\description{
Sample approximate plausible values under fitted posterior scoring
}
\details{
\code{sample_mfrm_plausible_values()} is a thin public wrapper around
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}} that exposes the fixed-calibration posterior draws as
a standalone object. It is useful when downstream workflows want repeated
latent-value imputations rather than just one posterior EAP summary.

In the current \code{mfrmr} implementation these are \strong{approximate plausible
values} drawn from the fitted quadrature-grid posterior under the scoring
basis implied by \code{fit}. For ordinary \code{MML} fits this is the fitted marginal
calibration; for latent-regression \code{MML} fits it is the fitted conditional
normal population model for the scored persons; for \code{JML} fits it is the
fixed facet/step calibration together with a standard normal reference prior
on the quadrature grid. They should be interpreted as posterior uncertainty
summaries for the scored persons, not as deterministic future truth values
and not as a claim of full many-facet plausible-values equivalence with
population-model software.

In other words, the \code{JML} path here is a practical scoring approximation
layered on top of the fitted joint-likelihood calibration, whereas the
latent-regression \code{MML} path uses the fitted one-dimensional conditional
normal population model. Neither path should be described as a full
many-facet plausible-values system with all ConQuest-style extensions.
}
\section{Interpreting output}{

\itemize{
\item \code{values} contains one row per person per draw.
\item \code{estimates} contains the companion posterior EAP summaries from
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}}.
\item \code{summary()} reports draw counts and empirical draw summaries by person.
}
}

\section{What this does not justify}{

This helper does not update the calibration, estimate new non-person facet
levels, or provide exact future true values. It samples from the fixed-grid
posterior implied by the existing fixed calibration.
}

\section{References}{

The underlying posterior scoring follows the usual quadrature-based EAP
framework of Bock and Aitkin (1981). The interpretation of multiple
posterior draws as plausible-value-style summaries follows the general logic
discussed by Mislevy (1991), while the current implementation remains a
practical fixed-calibration approximation rather than a full published
many-facet plausible-values method. For \code{JML} source fits, the quadrature
posterior uses a package-level standard normal reference prior for this
post hoc scoring layer.
\itemize{
\item Bock, R. D., & Aitkin, M. (1981). \emph{Marginal maximum likelihood estimation
of item parameters: Application of an EM algorithm}. Psychometrika, 46(4),
443-459.
\item Mislevy, R. J. (1991). \emph{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 = 30
  )
)
new_units <- data.frame(
  Person = c("NEW01", "NEW01"),
  Rater = unique(toy$Rater)[1],
  Criterion = unique(toy$Criterion)[1:2],
  Score = c(2, 3)
)
pv <- sample_mfrm_plausible_values(toy_fit, new_units, n_draws = 3, seed = 1)
summary(pv)$draw_summary
}
\seealso{
\code{\link[=predict_mfrm_units]{predict_mfrm_units()}}, \link{summary.mfrm_plausible_values}
}
