% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{dif_report}
\alias{dif_report}
\title{Generate a differential-functioning interpretation report}
\usage{
dif_report(dif_result, ...)
}
\arguments{
\item{dif_result}{Output from \code{\link[=analyze_dff]{analyze_dff()}} / \code{\link[=analyze_dif]{analyze_dif()}}
(class \code{mfrm_dff} with compatibility class \code{mfrm_dif}) or
\code{\link[=dif_interaction_table]{dif_interaction_table()}} (class \code{mfrm_dif_interaction}).}

\item{...}{Currently unused; reserved for future extensions.}
}
\value{
Object of class \code{mfrm_dif_report} with \code{narrative},
\code{counts}, \code{large_dif}, \code{gpcm_boundary}, and \code{config}.
}
\description{
Produces APA-style narrative text interpreting the results of a differential-
functioning analysis or interaction table. For \code{method = "refit"}, the
report summarises the number of facet levels classified as negligible (A),
moderate (B), and large (C). For \code{method = "residual"}, it summarises
screening-positive results, lists the specific levels and their direction,
and includes a caveat about the distinction between construct-relevant
variation and measurement bias.
}
\details{
When \code{dif_result} is an \code{mfrm_dff}/\code{mfrm_dif} object, the report is based on
the pairwise differential-functioning contrasts in \verb{$dif_table}. When it is an
\code{mfrm_dif_interaction} object, the report uses the cell-level
statistics and flags from \verb{$table}.

For \code{method = "refit"}, ETS-style magnitude labels are used only when
subgroup calibrations were successfully linked back to a common baseline
scale; otherwise the report labels those contrasts as unclassified because
the refit difference is descriptive rather than comparable on a linked
logit scale. For \code{method = "residual"}, the report describes
screening-positive versus screening-negative contrasts instead of applying
ETS labels.
}
\section{Interpreting output}{

\itemize{
\item \verb{$narrative}: character scalar with the full narrative text.
\item \verb{$counts}: named integer vector of method-appropriate counts.
\item \verb{$large_dif}: tibble of large ETS results (\code{method = "refit"}) or
screening-positive contrasts/cells (\code{method = "residual"}).
\item \verb{$gpcm_boundary}: for bounded \code{GPCM} inputs, a capability-boundary table
marking the narrative as caveated DFF screening output.
\item \verb{$config}: analysis configuration inherited from the input.
}
}

\section{GPCM boundary}{

If the input comes from a bounded \code{GPCM} fit, the narrative includes a
bounded-\code{GPCM} note and the returned report carries \code{gpcm_boundary}.
Treat the text as slope-aware screening/reporting support, not as a
standalone fairness, invariance, or operational subgroup decision.
}

\section{Typical workflow}{

\enumerate{
\item Run \code{\link[=analyze_dff]{analyze_dff()}} / \code{\link[=analyze_dif]{analyze_dif()}} or \code{\link[=dif_interaction_table]{dif_interaction_table()}}.
\item Pass the result to \code{dif_report()}.
\item Print the report or extract \verb{$narrative} for inclusion in a
manuscript.
}
}

\section{References}{

The narrative caveat about distinguishing construct-relevant variation
from unwanted measurement bias is grounded in:
\itemize{
\item Eckes, T. (2011). \emph{Introduction to Many-Facet Rasch Measurement:
Analyzing and Evaluating Rater-Mediated Assessments}. Frankfurt am
Main: Peter Lang. ISBN 978-3-631-61350-4.
\item McNamara, T., & Knoch, U. (2012). The Rasch wars: The emergence of
Rasch measurement in language testing. \emph{Language Testing}, 29(4),
555--576. \doi{10.1177/0265532211430367}
}
}

\examples{
toy <- load_mfrmr_data("example_bias")

fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 30)
diag <- diagnose_mfrm(fit, residual_pca = "none")
dif <- analyze_dff(fit, diag, facet = "Rater", group = "Group", data = toy)
rpt <- dif_report(dif)
cat(rpt$narrative)
}
\seealso{
\code{\link[=analyze_dff]{analyze_dff()}}, \code{\link[=analyze_dif]{analyze_dif()}}, \code{\link[=dif_interaction_table]{dif_interaction_table()}},
\code{\link[=plot_dif_heatmap]{plot_dif_heatmap()}}, \code{\link[=build_apa_outputs]{build_apa_outputs()}}
}
