% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-estimation.R
\name{describe_mfrm_data}
\alias{describe_mfrm_data}
\title{Summarize MFRM input data (TAM-style descriptive snapshot)}
\usage{
describe_mfrm_data(
  data,
  person,
  facets,
  score,
  weight = NULL,
  rating_min = NULL,
  rating_max = NULL,
  keep_original = FALSE,
  missing_codes = NULL,
  include_person_facet = FALSE,
  include_agreement = TRUE,
  rater_facet = NULL,
  context_facets = NULL,
  agreement_top_n = NULL
)
}
\arguments{
\item{data}{A data.frame in long format (one row per rating event).}

\item{person}{Column name for person IDs.}

\item{facets}{Character vector of facet column names.}

\item{score}{Column name for observed score.}

\item{weight}{Optional weight/frequency column name.}

\item{rating_min}{Optional minimum category value. Supply with
\code{rating_max} to retain unused boundary categories in the intended score
support.}

\item{rating_max}{Optional maximum category value. Supply with
\code{rating_min} to retain unused boundary categories in the intended score
support.}

\item{keep_original}{Keep original category values. Use this with
\code{rating_min} / \code{rating_max} when the intended scale has unused
intermediate categories such as \verb{1, 2, 4, 5} on a 1-5 scale.}

\item{missing_codes}{Optional. \code{NULL} (default) is a no-op;
\code{TRUE} or \code{"default"} activates the FACETS / SPSS / SAS
convention (\code{c("99", "999", "-1", "N", "NA", "n/a", ".", "")});
supply a character vector for a custom code set. Replacement
counts are returned in the \code{missing_recoding} component when
supported by the calling helper. See \code{\link[=recode_missing_codes]{recode_missing_codes()}}
for the standalone version.}

\item{include_person_facet}{If \code{TRUE}, include person-level rows in
\code{facet_level_summary}.}

\item{include_agreement}{If \code{TRUE}, include an observed-score inter-rater
agreement bundle (summary/pairs/settings) in the output.}

\item{rater_facet}{Optional rater facet name used for agreement summaries.
If \code{NULL}, inferred from facet names.}

\item{context_facets}{Optional facets used to define matched contexts for
agreement. If \code{NULL}, all remaining facets (including \code{Person}) are used.}

\item{agreement_top_n}{Optional maximum number of agreement pair rows.}
}
\value{
A list of class \code{mfrm_data_description} with:
\itemize{
\item \code{overview}: one-row run-level summary
\item \code{missing_by_column}: missing counts in selected input columns
\item \code{missing_rate_summary}: per-column missingness rate summary
(one row per input column, with raw and proportion-of-N columns)
\item \code{score_descriptives}: output from \code{\link[psych:describe]{psych::describe()}} for score
\item \code{weight_descriptives}: output from \code{\link[psych:describe]{psych::describe()}} for weight
\item \code{score_distribution}: weighted and raw score frequencies over the prepared
score support. Unused boundary categories are retained when the rating
range was supplied explicitly; unused intermediate categories require
\code{keep_original = TRUE}.
\item \code{facet_level_summary}: per-level usage and score summaries
\item \code{facet_crosstabs}: pairwise observation-count crosstabs between
non-person facets (named list keyed \code{"facetA__facetB"}); used by
\code{summary(ds)$design_links} to flag sparse / disconnected
facet-pair coverage
\item \code{linkage_summary}: person-facet connectivity diagnostics
\item \code{agreement}: observed-score inter-rater agreement bundle
\item \code{row_retention}: row counts before and after preparation filters
\item \code{preparation_notes}: structured notes for row drops, ID trimming, and
design conditions detected during preparation
\item \code{score_support}: minimal prepared score-support metadata used by
\code{summary(ds)$caveats}
}
}
\description{
Summarize MFRM input data (TAM-style descriptive snapshot)
}
\details{
This function provides a compact descriptive bundle similar to the
pre-fit summaries commonly checked in TAM workflows:
sample size, score distribution, per-facet coverage, and linkage counts.
\code{psych::describe()} is used for numeric descriptives of score and weight.

\strong{Key data-quality checks to perform before fitting:}
\itemize{
\item \emph{Sparse categories}: any score category with fewer than 10 weighted
observations may produce unstable threshold estimates
(Linacre, 2002).  Consider collapsing adjacent categories.
\item \emph{Unlinked elements}: if a facet level has zero overlap with one or
more levels of another facet, the design is disconnected and
parameters cannot be placed on a common scale.  Check
\code{linkage_summary} for low connectivity.
\item \emph{Extreme scores}: persons or facet levels with all-minimum or
all-maximum scores yield infinite logit estimates under JML;
they are handled via Bayesian shrinkage under MML.
}
}
\section{Interpreting output}{

Recommended order:
\itemize{
\item \code{overview}: confirms sample size, facet count, and category span.
The \code{MinWeightedN} column shows the smallest weighted observation
count across all facet levels; values below 30 may lead to
unstable parameter estimates.
\item \code{missing_by_column}: identifies immediate data-quality risks.
Any non-zero count warrants investigation before fitting.
\item \code{score_distribution}: checks sparse/unused score categories.
Balanced usage across categories is ideal; heavily skewed
distributions may compress the measurement range.
\item \code{facet_level_summary} and \code{linkage_summary}: checks per-level
support and person-facet connectivity.  Low linkage ratios
indicate sparse or disconnected design blocks.
\item \code{agreement}: optional observed inter-rater consistency summary
(exact agreement, correlation, mean differences per rater pair).
}
}

\section{Typical workflow}{

\enumerate{
\item Run \code{describe_mfrm_data()} on long-format input.
\item Review \code{summary(ds)} and \code{plot(ds, ...)}.
\item Resolve missingness/sparsity issues before \code{\link[=fit_mfrm]{fit_mfrm()}}.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
ds <- describe_mfrm_data(
  data = toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score"
)
s_ds <- summary(ds)
s_ds$overview
p_ds <- plot(ds, draw = FALSE)
p_ds$data$plot
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}}
}
