% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-facet-equivalence.R
\name{plot_facet_equivalence}
\alias{plot_facet_equivalence}
\title{Plot facet-equivalence results}
\usage{
plot_facet_equivalence(
  x,
  diagnostics = NULL,
  facet = NULL,
  type = c("forest", "rope"),
  draw = TRUE,
  ...
)
}
\arguments{
\item{x}{Output from \code{\link[=analyze_facet_equivalence]{analyze_facet_equivalence()}} or \code{\link[=fit_mfrm]{fit_mfrm()}}.}

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

\item{facet}{Facet to analyze when \code{x} is an \code{mfrm_fit} object.}

\item{type}{Plot type: \code{"forest"} (default) or \code{"rope"}.}

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

\item{...}{Additional graphical arguments passed to base plotting functions.}
}
\value{
Invisibly returns the plotting data. If \code{draw = FALSE}, the plotting
data are returned without drawing.
}
\description{
Plot facet-equivalence results
}
\details{
\code{plot_facet_equivalence()} is a visual companion to
\code{\link[=analyze_facet_equivalence]{analyze_facet_equivalence()}}. It does not recompute the equivalence
analysis; it only reshapes and displays the returned results.
}
\section{Plot types}{

\itemize{
\item \code{"forest"} places each level on the logit scale with its confidence
interval and shades the practical-equivalence region around the weighted
grand mean.
\item \code{"rope"} shows the percentage of each level's uncertainty mass that falls
inside the ROPE.
}
}

\section{Interpreting output}{

In the \strong{forest plot}, the shaded band marks the ROPE
(\eqn{\pm}\code{equivalence_bound} around the weighted grand mean).
Levels whose entire confidence interval lies inside this band are
close to the facet grand mean under this descriptive screen. Levels whose
interval extends outside the band are more displaced from the facet average.
Overlapping intervals between two elements suggest they are not
reliably separable, but overlap alone does not establish formal
equivalence---use the TOST results for that.

In the \strong{ROPE bar chart}, each bar shows the proportion of the
element's normal-approximation distribution that falls inside the
ROPE-style grand-mean proximity.  Values > 95\\% indicate that most of
the element's normal-approximation uncertainty falls near the facet
average; 50--95\\% is indeterminate; < 50\\% suggests the element is
meaningfully displaced from that average.
}

\section{Typical workflow}{

\enumerate{
\item Run \code{\link[=analyze_facet_equivalence]{analyze_facet_equivalence()}}.
\item Start with \code{type = "forest"} to see the facet on the logit scale.
\item Switch to \code{type = "rope"} when you want a ranking of levels by
grand-mean proximity.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 30)
eq <- analyze_facet_equivalence(fit, facet = "Rater")
pdat <- plot_facet_equivalence(eq, type = "forest", draw = FALSE)
c(pdat$facet, pdat$type)
}
\seealso{
\code{\link[=analyze_facet_equivalence]{analyze_facet_equivalence()}}
}
\concept{confidence intervals}
\concept{facet equivalence}
\concept{visual diagnostics}
