% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-prediction.R
\name{predict_mfrm_population}
\alias{predict_mfrm_population}
\title{Forecast population-level MFRM operating characteristics for one future design}
\usage{
predict_mfrm_population(
  fit = NULL,
  sim_spec = NULL,
  n_person = NULL,
  n_rater = NULL,
  n_criterion = NULL,
  raters_per_person = NULL,
  design = NULL,
  reps = 50,
  fit_method = NULL,
  model = NULL,
  maxit = 25,
  quad_points = 7,
  residual_pca = c("none", "overall", "facet", "both"),
  seed = NULL
)
}
\arguments{
\item{fit}{Optional output from \code{\link[=fit_mfrm]{fit_mfrm()}} used to derive a fit-based
simulation specification.}

\item{sim_spec}{Optional output from \code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}} or
\code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}}. Supply exactly one of \code{fit} or \code{sim_spec}.}

\item{n_person}{Number of persons/respondents in the future design. Defaults
to the value stored in the base simulation specification.}

\item{n_rater}{Number of rater facet levels in the future design. Defaults to
the value stored in the base simulation specification.}

\item{n_criterion}{Number of criterion/item facet levels in the future
design. Defaults to the value stored in the base simulation specification.}

\item{raters_per_person}{Number of raters assigned to each person in the
future design. Defaults to the value stored in the base simulation
specification.}

\item{design}{Optional named design override supplied as a named list,
named vector, or one-row data frame. Names may use canonical variables
(\code{n_person}, \code{n_rater}, \code{n_criterion}, \code{raters_per_person}), current
public aliases (for example \code{n_judge}, \code{n_task}, \code{judge_per_person}), or
role keywords (\code{person}, \code{rater}, \code{criterion}, \code{assignment}). The
schema-only future branch input \code{design$facets = c(person = ..., judge = ..., task = ...)} is also accepted for the currently exposed facet keys.
Do not specify the same variable through both \code{design} and the scalar
count arguments.}

\item{reps}{Number of replications used in the forecast simulation.}

\item{fit_method}{Estimation method used inside the forecast simulation. When
\code{fit} is supplied, defaults to that fit's estimation method; otherwise
defaults to \code{"MML"}.}

\item{model}{Measurement model used when refitting the forecasted design.
Defaults to the model recorded in the base simulation specification.}

\item{maxit}{Maximum iterations passed to \code{\link[=fit_mfrm]{fit_mfrm()}} in each replication.}

\item{quad_points}{Quadrature points for \code{fit_method = "MML"}.}

\item{residual_pca}{Residual PCA mode passed to \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{seed}{Optional seed for reproducible replications.}
}
\value{
An object of class \code{mfrm_population_prediction} with components:
\itemize{
\item \code{design}: requested future design
\item \code{forecast}: facet-level forecast table
\item \code{overview}: run-level overview
\item \code{simulation}: underlying \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}} result
\item \code{sim_spec}: simulation specification used for the forecast
\item \code{facet_names}: public non-person facet names carried by the simulation
specification
\item \code{design_variable_aliases}: public aliases for
\code{n_person}/\code{n_rater}/\code{n_criterion}/\code{raters_per_person}
\item \code{design_descriptor}: role-based description of design variables carried
from the underlying planning object
\item \code{planning_scope}: explicit record of the current planning contract,
including a \code{facet_manifest} and future-planner scaffold marker
\item \code{planning_constraints}: explicit record of mutable/locked design variables
\item \code{planning_schema}: combined planner-schema contract carrying the role
table, current boundary, mutability map, facet manifest, and a
schema-only future facet-count table
\item \code{gpcm_boundary}: bounded-\code{GPCM} caveat row when a \code{GPCM} forecast route is
used
\item \code{settings}: forecasting settings
\item \code{ademp}: simulation-study metadata
\item \code{notes}: interpretation notes
}
}
\description{
Forecast population-level MFRM operating characteristics for one future design
}
\details{
\code{predict_mfrm_population()} is a \strong{scenario-level forecasting helper} built
on top of \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}. It is intended for questions such as:
\itemize{
\item what separation/reliability would we expect if the next administration had
60 persons, 4 raters, and 2 ratings per person?
\item how much Monte Carlo uncertainty remains around those expected summaries?
}

The function deliberately returns \strong{aggregate operating characteristics}
(for example mean separation, reliability, recovery RMSE, convergence rate)
rather than future individual true values for one respondent or one rater.

If \code{fit} is supplied, the function first constructs a fit-derived parametric
starting point with \code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}} and then evaluates the
requested future design under that explicit data-generating mechanism. This
should be interpreted as a fit-based forecast under modeling assumptions, not
as a guaranteed out-of-sample prediction.

When that fit-derived or manually built simulation specification stores an
active latent-regression population generator, the helper still operates at
the \strong{design / operating-characteristic} level. It repeatedly simulates
person-level covariates and responses, refits the MML population-model
branch, and summarizes the resulting facet-level behavior. This is distinct
from the fitted-model posterior scoring provided by \code{\link[=predict_mfrm_units]{predict_mfrm_units()}}.

Bounded \code{GPCM} forecasts are available with caveats through the same
repeated simulation/refit design route used by \code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}.
They summarize design-level operating characteristics under the supplied or
fit-derived slope-aware specification; they do not validate operational
scoring, diagnostic-screening or signal-detection rules, slope-recovery
adequacy, or arbitrary-facet planning.
}
\section{Interpreting output}{

\itemize{
\item \code{forecast} contains facet-level expected summaries for the requested
future design.
\item \verb{Mcse*} columns quantify Monte Carlo uncertainty from using a finite number
of replications.
\item \code{design_variable_aliases} and \code{design_descriptor} carry the same public
naming metadata used by the underlying planning object. They rename the
standard two non-person facet roles for presentation, but they do not turn
the current planner into a fully arbitrary-facet simulator.
\item If \code{sim_spec$population$active = TRUE}, the forecast summarizes repeated
latent-regression MML refits under that stored person-level generator; it
is still a scenario forecast rather than direct posterior scoring for one
observed sample.
\item \code{simulation} stores the full design-evaluation object in case you want to
inspect replicate-level behavior.
}
}

\section{What this does not justify}{

This helper does not produce definitive future person measures or rater
severities for one concrete sample. It forecasts design-level behavior under
the supplied or derived parametric assumptions.
}

\section{References}{

The forecast is implemented as a one-scenario Monte Carlo / operating-
characteristic study following the general guidance of Morris, White, and
Crowther (2019) and the ADEMP-oriented reporting framework discussed by
Siepe et al. (2024). In \code{mfrmr}, this function is a practical wrapper for
future-design planning rather than a direct implementation of a published
many-facet forecasting procedure.
\itemize{
\item Morris, T. P., White, I. R., & Crowther, M. J. (2019).
\emph{Using simulation studies to evaluate statistical methods}.
Statistics in Medicine, 38(11), 2074-2102.
\item Siepe, B. S., Bartos, F., Morris, T. P., Boulesteix, A.-L., Heck, D. W.,
& Pawel, S. (2024). \emph{Simulation studies for methodological research in
psychology: A standardized template for planning, preregistration, and
reporting}. Psychological Methods.
}
}

\examples{
\donttest{
spec <- build_mfrm_sim_spec(
  n_person = 16,
  n_rater = 3,
  n_criterion = 2,
  raters_per_person = 2,
  assignment = "rotating"
)
pred <- predict_mfrm_population(
  sim_spec = spec,
  design = list(person = 18),
  reps = 1,
  maxit = 30,
  seed = 123
)
s_pred <- summary(pred)
s_pred$forecast[, c("Facet", "MeanSeparation", "McseSeparation")]
}
}
\seealso{
\code{\link[=build_mfrm_sim_spec]{build_mfrm_sim_spec()}}, \code{\link[=extract_mfrm_sim_spec]{extract_mfrm_sim_spec()}},
\code{\link[=evaluate_mfrm_design]{evaluate_mfrm_design()}}, \link{summary.mfrm_population_prediction}
}
