% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-export-bundles.R
\name{normalize_conquest_overlap_tables}
\alias{normalize_conquest_overlap_tables}
\title{Normalize extracted ConQuest overlap tables to the \code{mfrmr} review contract}
\usage{
normalize_conquest_overlap_tables(
  conquest_population,
  conquest_item_estimates,
  conquest_case_eap,
  conquest_population_term = "auto",
  conquest_population_estimate = "auto",
  conquest_item_id = "auto",
  conquest_item_estimate = "auto",
  conquest_case_person = "auto",
  conquest_case_estimate = "auto",
  keep_extra_columns = TRUE
)
}
\arguments{
\item{conquest_population}{Extracted ConQuest population-parameter table as a
data.frame.}

\item{conquest_item_estimates}{Extracted ConQuest item-estimate table as a
data.frame.}

\item{conquest_case_eap}{Extracted ConQuest case-level EAP table as a
data.frame.}

\item{conquest_population_term}{Column in \code{conquest_population} that stores
parameter names. \code{"auto"} tries conservative aliases such as \code{Parameter}
and \code{Term}.}

\item{conquest_population_estimate}{Column in \code{conquest_population} that
stores parameter estimates. \code{"auto"} tries aliases such as \code{Estimate} and
\code{Est}.}

\item{conquest_item_id}{Column in \code{conquest_item_estimates} that stores the
item identifier as exported or extracted by the user. \code{"auto"} tries
aliases such as \code{ResponseVar}, \code{ItemID}, \code{Item}, and \code{Label}.}

\item{conquest_item_estimate}{Column in \code{conquest_item_estimates} that stores
item estimates. \code{"auto"} tries aliases such as \code{Estimate}, \code{Est}, and
\code{Facility}.}

\item{conquest_case_person}{Column in \code{conquest_case_eap} that stores person
IDs. \code{"auto"} tries conservative aliases such as \code{Person}, \code{PID}, and
\verb{Sequence ID}.}

\item{conquest_case_estimate}{Column in \code{conquest_case_eap} that stores case
EAP estimates. \code{"auto"} tries conservative aliases such as \code{Estimate},
\code{EAP_1}, and \code{EAP}.}

\item{keep_extra_columns}{If \code{TRUE}, keep all remaining columns after the
standardized identifier and estimate columns.}
}
\value{
A named list with class \code{mfrm_conquest_overlap_tables}.
}
\description{
Normalize extracted ConQuest overlap tables to the \code{mfrmr} review contract
}
\details{
This helper does not parse raw ConQuest text output. It standardizes already
extracted tables to the contract used by \code{\link[=review_conquest_overlap]{review_conquest_overlap()}}:
\itemize{
\item population parameters become columns \code{Parameter}, \code{Estimate}, and
\code{EstimateNonNumeric};
\item item estimates become columns \code{ItemID}, \code{Estimate}, and
\code{EstimateNonNumeric};
\item case summaries become columns \code{Person}, \code{Estimate}, and
\code{EstimateNonNumeric}.
}

The resulting object is intentionally conservative. It does not infer
whether item IDs correspond to exported response variables or original item
levels; that matching step remains part of \code{\link[=review_conquest_overlap]{review_conquest_overlap()}}, where
the standardized ConQuest tables are compared against a concrete overlap
bundle.
}
\section{Output}{

The returned object has class \code{mfrm_conquest_overlap_tables} and includes:
\itemize{
\item \code{summary}: one-row normalization summary
\item \code{conquest_population}: standardized population table
\item \code{conquest_item_estimates}: standardized item table
\item \code{conquest_case_eap}: standardized case table
\item \code{settings}: source-column metadata
\item \code{notes}: interpretation notes
}

Read \code{summary(normalized)$normalization_scope} before review to confirm
that the object contains extracted tabular inputs, not parsed raw ConQuest
report text, and to check duplicate-ID / non-numeric-estimate pre-review
flags.
}

\examples{
normalized <- normalize_conquest_overlap_tables(
  conquest_population = data.frame(
    Term = c("(Intercept)", "GroupB", "sigma2"),
    Est = c(0, 0.2, 1)
  ),
  conquest_item_estimates = data.frame(
    Item = c("I1", "I2"),
    Est = c(-0.2, 0.2)
  ),
  conquest_case_eap = data.frame(
    PID = c("P001", "P002"),
    EAP = c(-0.1, 0.1)
  ),
  conquest_population_term = "Term",
  conquest_population_estimate = "Est",
  conquest_item_id = "Item",
  conquest_item_estimate = "Est",
  conquest_case_person = "PID",
  conquest_case_estimate = "EAP"
)
summary(normalized)$normalization_scope
}
\seealso{
\code{\link[=build_conquest_overlap_bundle]{build_conquest_overlap_bundle()}}, \code{\link[=review_conquest_overlap]{review_conquest_overlap()}}
}
