% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-plotting-secondary.R
\name{plot_shrinkage_funnel}
\alias{plot_shrinkage_funnel}
\title{Empirical-Bayes shrinkage funnel / caterpillar}
\usage{
plot_shrinkage_funnel(
  fit,
  facet = NULL,
  top_n = 30L,
  preset = c("standard", "publication", "compact", "monochrome"),
  show_ci = FALSE,
  ci_level = 0.95,
  draw = TRUE
)
}
\arguments{
\item{fit}{An \code{mfrm_fit} augmented with empirical-Bayes shrinkage.}

\item{facet}{Facet to draw (default: first non-person facet with
shrinkage columns present).}

\item{top_n}{Maximum number of rows to draw (default 30).}

\item{preset}{Visual preset.}

\item{show_ci}{Logical. When \code{TRUE}, draw approximate confidence-interval
whiskers for raw and shrunken estimates when \code{SE} / \code{ShrunkSE} evidence is
available.}

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

\item{draw}{If \code{TRUE}, draw with base graphics.}
}
\value{
An \code{mfrm_plot_data} whose \code{data} slot bundles the long
\code{Level}, \code{RawEstimate}, \code{ShrunkEstimate}, \code{ShrinkageFactor} table.
When \code{show_ci = TRUE}, the table also includes \code{RawCI_Lower},
\code{RawCI_Upper}, \code{ShrunkCI_Lower}, \code{ShrunkCI_Upper}, and \code{CI_Level}.
}
\description{
Visualizes empirical-Bayes shrinkage by drawing one row per facet
level with the raw (pre-shrinkage) and shrunken estimates plus the
shrinkage factor. Rows are ordered by absolute shrinkage so the
levels that move most under the prior appear at the top.
}
\details{
Requires a fit produced via \code{\link[=apply_empirical_bayes_shrinkage]{apply_empirical_bayes_shrinkage()}} or
a \code{fit_mfrm(..., facet_shrinkage = "empirical_bayes")} run, so that
\code{fit$facets$others} carries \code{Estimate}, \code{ShrunkEstimate}, and
\code{ShrinkageFactor} columns.
}
\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 30)
fit_eb <- apply_empirical_bayes_shrinkage(fit)
p <- plot_shrinkage_funnel(fit_eb, draw = FALSE)
head(p$data$table)
# Look for: short segments (Raw and Shrunken close together) =
#   little pooling. Long segments fanning toward the centre = the
#   prior pulled the estimate strongly; this is most pronounced for
#   small-N levels. ShrinkageFactor near 1 means most of the
#   movement was driven by the prior rather than the data.
}
\seealso{
\code{\link[=apply_empirical_bayes_shrinkage]{apply_empirical_bayes_shrinkage()}},
\link{mfrmr_visual_diagnostics}
}
