% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{plot_wright_unified}
\alias{plot_wright_unified}
\title{Plot a unified Wright map with all facets on a shared logit scale}
\usage{
plot_wright_unified(
  fit,
  diagnostics = NULL,
  bins = 20L,
  show_thresholds = TRUE,
  top_n = 30L,
  show_ci = FALSE,
  ci_level = 0.95,
  draw = TRUE,
  preset = c("standard", "publication", "compact", "monochrome"),
  palette = NULL,
  label_angle = 45,
  ...
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{bins}{Integer number of bins for the person histogram. Default \code{20}.}

\item{show_thresholds}{Logical; if \code{TRUE}, display threshold/step
positions on the map. Default \code{TRUE}.}

\item{top_n}{Maximum number of facet/step points retained for labeling.}

\item{show_ci}{Logical; if \code{TRUE}, draw approximate confidence intervals when
standard errors are available.}

\item{ci_level}{Confidence level used when \code{show_ci = TRUE}.}

\item{draw}{If \code{TRUE} (default), draw the plot. If \code{FALSE}, return
plot data invisibly.}

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

\item{palette}{Optional named color overrides passed to the shared Wright-map
drawer.}

\item{label_angle}{Rotation angle for group labels on the facet panel.}

\item{...}{Additional graphical parameters.}
}
\value{
Invisibly, a list with \code{persons}, \code{facets}, and \code{thresholds}
data used for the plot.
}
\description{
Produces a shared-logit variable map showing person ability distribution
alongside measure estimates for every facet in side-by-side columns on
the same scale.
}
\details{
This unified map arranges:
\itemize{
\item Column 1: Person measure distribution (horizontal histogram)
\item Shared facet/step panel: facet levels and optional threshold positions on
the same vertical logit axis
\item Range and interquartile overlays for each facet group to show spread
}

This is the package's most compact targeting view when you want one display
that shows where persons, facet levels, and category thresholds sit
relative to the same latent scale.

The logit scale on the y-axis is shared, allowing direct visual
comparison of all facets and persons.
}
\section{Interpreting output}{

\itemize{
\item Facet levels at the same height on the map are at similar difficulty.
\item The person histogram shows where examinees cluster relative to the
facet scale.
\item Thresholds (if shown) indicate category boundary positions.
\item Large gaps between the person distribution and facet locations can signal
targeting problems.
}
}

\section{Typical workflow}{

\enumerate{
\item Fit a model with \code{\link[=fit_mfrm]{fit_mfrm()}}.
\item Plot with \code{plot_wright_unified(fit)}.
\item Compare person distribution with facet level locations.
\item Use \code{show_thresholds = TRUE} when you want the category structure in the
same view.
}
}

\section{When to use this instead of plot_information}{

Use \code{plot_wright_unified()} when your main question is targeting or coverage
on the shared logit scale. Use \code{\link[=plot_information]{plot_information()}} when your main question
is measurement precision across theta.
}

\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")
toy_small <- toy[toy$Person \%in\% unique(toy$Person)[1:12], , drop = FALSE]
fit <- fit_mfrm(toy_small, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 30)
map_data <- plot_wright_unified(fit, draw = FALSE)
names(map_data)
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=plot.mfrm_fit]{plot.mfrm_fit()}}, \link{mfrmr_visual_diagnostics}
}
\concept{Wright maps}
\concept{confidence intervals}
\concept{visual diagnostics}
