% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-resampling.R
\name{build_mfrm_resampling_spec}
\alias{build_mfrm_resampling_spec}
\title{Build an observed-data resampling specification}
\usage{
build_mfrm_resampling_spec(
  data,
  person,
  facets,
  score,
  strata = NULL,
  preserve_facets = NULL,
  design = c("stratified_subsample", "stratified_bootstrap"),
  reps = 20,
  sample_fraction = 0.5,
  sample_n = NULL,
  replace = NULL,
  seed = NULL,
  min_per_stratum = 1,
  topup_preserve_facets = TRUE
)
}
\arguments{
\item{data}{A long-format observed MFRM data set.}

\item{person}{Person/respondent identifier column.}

\item{facets}{Non-person facet columns used by the target MFRM fit.}

\item{score}{Ordered score column.}

\item{strata}{Optional person-level stratification columns, for example a
\code{Region} or L1 group column. Each person must have at most one unique
stratum combination.}

\item{preserve_facets}{Optional facet columns whose level coverage should be
reviewed and, when possible, topped up after the stratified person draw.
A common choice is the rater facet.}

\item{design}{Resampling design. \code{"stratified_subsample"} samples persons
without replacement inside each stratum. \code{"stratified_bootstrap"} samples
persons with replacement inside each stratum and re-keys duplicate person
instances in the returned data.}

\item{reps}{Number of resampling replicates to draw.}

\item{sample_fraction}{Fraction of persons to draw within each stratum when
\code{sample_n = NULL}.}

\item{sample_n}{Optional target number of persons to draw per stratum. Supply
either one scalar used for every stratum, or a named numeric vector whose
names match the computed stratum labels.}

\item{replace}{Optional logical override for replacement. By default,
replacement is \code{FALSE} for \code{"stratified_subsample"} and \code{TRUE} for
\code{"stratified_bootstrap"}.}

\item{seed}{Optional seed used by \code{\link[=draw_mfrm_resamples]{draw_mfrm_resamples()}}.}

\item{min_per_stratum}{Minimum target persons per represented stratum.}

\item{topup_preserve_facets}{Logical; if \code{TRUE}, add extra person clusters
when possible to recover missing levels of \code{preserve_facets}.}
}
\value{
An object of class \code{mfrm_resampling_spec}.
}
\description{
Build an observed-data resampling specification
}
\details{
This helper defines a resampling design for observed-data stability checks.
It is intentionally separate from \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}} and
\code{\link[=evaluate_mfrm_recovery]{evaluate_mfrm_recovery()}}. The full-data estimates used with these draws
are reference estimates, not known truth, so downstream summaries should be
described as estimation stability, reproducibility, or agreement with a
full-data reference rather than strict parameter recovery.

The design is person-clustered: all rows for a selected person are kept
together. For bootstrap draws, duplicated person clusters are re-keyed in the
returned data while the original identifier is retained in
\code{.mfrm_original_person}.
}
\examples{
toy <- simulate_mfrm_data(n_person = 12, n_rater = 3, n_criterion = 2,
                          raters_per_person = 2, seed = 11)
region_map <- setNames(rep(c("A", "B", "C"),
                           length.out = length(unique(toy$Person))),
                       unique(toy$Person))
toy$Region <- unname(region_map[toy$Person])
spec <- build_mfrm_resampling_spec(
  toy, person = "Person", facets = c("Rater", "Criterion"),
  score = "Score", strata = "Region", preserve_facets = "Rater",
  reps = 2, sample_fraction = 0.5, seed = 99
)
draws <- draw_mfrm_resamples(spec)
summary(draws)$overview
}
\seealso{
\code{\link[=draw_mfrm_resamples]{draw_mfrm_resamples()}}, \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}}
}
