% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting.R
\name{plot_displacement}
\alias{plot_displacement}
\title{Plot displacement diagnostics using base R}
\usage{
plot_displacement(
  x,
  diagnostics = NULL,
  anchored_only = FALSE,
  facets = NULL,
  plot_type = c("lollipop", "hist"),
  top_n = 40,
  show_ci = FALSE,
  ci_level = 0.95,
  preset = c("standard", "publication", "compact", "monochrome"),
  draw = TRUE,
  ...
)
}
\arguments{
\item{x}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}} or \code{\link[=displacement_table]{displacement_table()}}.}

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

\item{anchored_only}{Keep only anchored/group-anchored levels.}

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

\item{plot_type}{\code{"lollipop"} or \code{"hist"}.}

\item{top_n}{Maximum levels shown in \code{"lollipop"} mode.}

\item{show_ci}{Logical. When \code{TRUE} and \code{plot_type = "lollipop"}, draw
approximate confidence-interval whiskers from \code{DisplacementSE}
(ignored for \code{"hist"}).}

\item{ci_level}{Confidence level used when \code{show_ci = TRUE}; default
\code{0.95}. The returned plot-data object gains \code{CI_Lower} / \code{CI_Upper}
/ \code{CI_Level} columns on the \code{table} element for downstream reuse.}

\item{preset}{Visual preset (\code{"standard"}, \code{"publication"}, \code{"compact"}, or \code{"monochrome"}).}

\item{draw}{If \code{TRUE}, draw with base graphics.}

\item{...}{Additional arguments passed to \code{\link[=displacement_table]{displacement_table()}} when \code{x} is \code{mfrm_fit}.}
}
\value{
A plotting-data object of class \code{mfrm_plot_data}.
}
\description{
Plot displacement diagnostics using base R
}
\details{
\strong{Displacement} quantifies how much a single element's calibration
would shift the overall model if it were allowed to move freely.
It is computed as:

\deqn{\mathrm{Displacement}_j = \frac{\sum_i (X_{ij} - E_{ij})}
                                     {\sum_i \mathrm{Var}_{ij}}}

where the sums run over all observations involving element \eqn{j}.
The standard error is \eqn{1 / \sqrt{\sum_i \mathrm{Var}_{ij}}}, and
a t-statistic \eqn{t = \mathrm{Displacement} / \mathrm{SE}} flags
elements whose observed residual pattern is inconsistent with the
current anchor structure.

Displacement is most informative after anchoring: large values suggest
that anchored values may be drifting from the current sample.
For non-anchored analyses, displacement reflects residual
calibration tension.
}
\section{Plot types}{

\describe{
\item{\code{"lollipop"} (default)}{Dot-and-line chart of displacement values.
X-axis: displacement (logits).  Y-axis: element labels.  Points
colored red when flagged (default: \eqn{|\mathrm{Disp.}| > 0.5}
logits).  Dashed lines at \eqn{\pm} threshold.  Ordered by
absolute displacement.}
\item{\code{"hist"}}{Histogram of displacement values with Freedman-Diaconis
breaks.  Dashed reference lines at \eqn{\pm} threshold.  Use for
inspecting the overall distribution shape.}
}
}

\section{Interpreting output}{

Lollipop: top absolute displacement levels; flagged points indicate
larger movement from anchor expectations.

Histogram: overall displacement distribution and threshold lines.
A symmetric distribution centred near zero indicates good anchor
stability; heavy tails or skew suggest systematic drift.

Use \code{anchored_only = TRUE} when your main question is anchor robustness.
}

\section{Typical workflow}{

\enumerate{
\item Run with \code{plot_type = "lollipop"} and \code{anchored_only = TRUE}.
\item Inspect distribution with \code{plot_type = "hist"}.
\item Drill into flagged rows via \code{\link[=displacement_table]{displacement_table()}}.
}
}

\section{Further guidance}{

For a plot-selection guide and a longer walkthrough, see
\link{mfrmr_visual_diagnostics} and
\code{vignette("mfrmr-visual-diagnostics", package = "mfrmr")}.
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 30)
p <- plot_displacement(fit, anchored_only = FALSE, draw = FALSE)
if (interactive()) {
  plot_displacement(
    fit,
    anchored_only = FALSE,
    plot_type = "lollipop",
    preset = "publication"
  )
}
}
\seealso{
\code{\link[=displacement_table]{displacement_table()}}, \code{\link[=plot_unexpected]{plot_unexpected()}}, \code{\link[=plot_fair_average]{plot_fair_average()}},
\code{\link[=plot_qc_dashboard]{plot_qc_dashboard()}}, \link{mfrmr_visual_diagnostics}
}
\concept{confidence intervals}
\concept{displacement}
\concept{visual diagnostics}
