% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-simulation-spec.R
\name{extract_mfrm_sim_spec}
\alias{extract_mfrm_sim_spec}
\title{Derive a simulation specification from a fitted MFRM object}
\usage{
extract_mfrm_sim_spec(
  fit,
  assignment = c("auto", "crossed", "rotating", "resampled", "skeleton"),
  latent_distribution = c("normal", "empirical"),
  source_data = NULL,
  person = NULL,
  group = NULL
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{assignment}{Assignment design to record in the returned specification.
Use \code{"resampled"} to reuse empirical person-level rater-assignment
profiles from the fitted data, or \code{"skeleton"} to reuse the observed
person-by-facet design skeleton from the fitted data.}

\item{latent_distribution}{Latent-value generator to record in the returned
specification. \code{"normal"} stores spread summaries for parametric draws;
\code{"empirical"} additionally activates centered empirical resampling from the
fitted person/rater/criterion estimates.}

\item{source_data}{Optional original source data used to recover additional
non-calibration columns, currently person-level \code{group} labels, when
building a fit-derived observed response skeleton.}

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

\item{group}{Optional group column name in \code{source_data} to merge into the
returned \code{design_skeleton} as person-level metadata.}
}
\value{
An object of class \code{mfrm_sim_spec}.
}
\description{
Derive a simulation specification from a fitted MFRM object
}
\details{
\code{extract_mfrm_sim_spec()} uses a fitted model as a practical starting point
for later simulation studies. It extracts:
\itemize{
\item design counts from the fitted data
\item empirical spread of person and facet estimates
\item optional empirical support values for semi-parametric draws
\item fitted threshold values
\item either a simplified assignment summary (\code{"crossed"} / \code{"rotating"}),
empirical resampled assignment profiles (\code{"resampled"}), or an observed
response skeleton (\code{"skeleton"}, optionally carrying \code{Group}/\code{Weight})
\item when the fit used the latent-regression branch, the fitted
\code{population_formula}, coefficient vector, residual variance, and the
stored person-level covariate table, including model-matrix xlevel and
contrast provenance for categorical covariates
}

This is intended as a \strong{fit-derived parametric starting point}, not as a
claim that the fitted object perfectly recovers the true data-generating
mechanism. Users should review and, if necessary, edit the returned
specification before using it for design planning.

First-release \code{GPCM} fits are now supported here for direct data generation
and parameter-recovery checks, provided that the returned simulation
specification stores both a threshold table and a parallel slope table.
The same fit-derived specification can feed caveated role-based design
evaluation, population forecasting, and fit-based report/export bundles.
Diagnostic/signal-detection design screening, full FACETS score-side
contract review, posterior predictive checks, and heavy backend extensions
remain outside the bounded-\code{GPCM} boundary until those downstream contracts
are widened explicitly.

If you want to carry person-level group labels into a fit-derived observed
response skeleton, provide the original \code{source_data} together with
\code{person} and \code{group}. Group labels are treated as person-level metadata and
are checked for one-label-per-person consistency before being merged.
}
\section{Interpreting output}{

The returned object is a simulation specification, not a prediction about one
future sample. It captures one convenient approximation to the observed
design and estimated spread in the fitted run.
}

\examples{
\donttest{
toy <- simulate_mfrm_data(
  n_person = 8,
  n_rater = 3,
  n_criterion = 2,
  seed = 123
)
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
spec <- extract_mfrm_sim_spec(fit, latent_distribution = "empirical")
spec$assignment
spec$model
head(spec$threshold_table)
}
}
\seealso{
\code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}}, \code{\link[=simulate_mfrm_data]{simulate_mfrm_data()}}
}
