% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-tables.R
\name{displacement_table}
\alias{displacement_table}
\title{Compute displacement diagnostics for facet levels}
\usage{
displacement_table(
  fit,
  diagnostics = NULL,
  facets = NULL,
  anchored_only = FALSE,
  abs_displacement_warn = 0.5,
  abs_t_warn = 2,
  top_n = NULL
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.}

\item{facets}{Optional subset of facets.}

\item{anchored_only}{If \code{TRUE}, keep only directly/group anchored levels.}

\item{abs_displacement_warn}{Absolute displacement warning threshold.}

\item{abs_t_warn}{Absolute displacement t-value warning threshold.}

\item{top_n}{Optional maximum number of rows to keep after sorting.}
}
\value{
A named list with:
\itemize{
\item \code{table}: displacement diagnostics by level
\item \code{summary}: one-row summary
\item \code{thresholds}: applied thresholds
}
}
\description{
Compute displacement diagnostics for facet levels
}
\details{
Displacement is computed as a one-step Newton update:
\code{sum(residual) / sum(information)} for each facet level.
This approximates how much a level would move if constraints were relaxed.
}
\section{Interpreting output}{

\itemize{
\item \code{table}: level-wise displacement and flag indicators.
\item \code{summary}: count/share of flagged levels.
\item \code{thresholds}: displacement and t-value cutoffs.
}

Large absolute displacement in anchored levels suggests potential instability
in anchor assumptions.
}

\section{Typical workflow}{

\enumerate{
\item Run \code{displacement_table(fit, anchored_only = TRUE)} for anchor checks.
\item Inspect \code{summary(disp)} then detailed rows.
\item Visualize with \code{\link[=plot_displacement]{plot_displacement()}}.
}
}

\section{Output columns}{

The \code{table} data.frame contains:
\describe{
\item{Facet, Level}{Facet name and element label.}
\item{Displacement}{One-step Newton displacement estimate (logits).}
\item{DisplacementSE}{Standard error of the displacement.}
\item{DisplacementT}{Displacement / SE ratio.}
\item{Estimate, SE}{Current measure estimate and its standard error.}
\item{N}{Number of observations involving this level.}
\item{AnchorValue, AnchorStatus, AnchorType}{Anchor metadata.}
\item{Flag}{Logical; \code{TRUE} when displacement exceeds thresholds.}
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
disp <- displacement_table(fit, anchored_only = FALSE)
summary(disp)
p_disp <- plot(disp, draw = FALSE)
p_disp$data$plot
}
\seealso{
\code{\link[=diagnose_mfrm]{diagnose_mfrm()}}, \code{\link[=unexpected_response_table]{unexpected_response_table()}}, \code{\link[=fair_average_table]{fair_average_table()}}
}
