% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-facet-equivalence.R
\name{analyze_facet_equivalence}
\alias{analyze_facet_equivalence}
\title{Analyze practical equivalence within a facet}
\usage{
analyze_facet_equivalence(
  fit,
  diagnostics = NULL,
  facet = NULL,
  equivalence_bound = 0.5,
  ci_level = 0.95,
  conf_level = NULL
)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{diagnostics}{Optional output from \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}. When \code{NULL},
diagnostics are computed with \code{residual_pca = "none"}.}

\item{facet}{Character scalar naming the non-person facet to evaluate. If
\code{NULL}, the function prefers a rater-like facet and otherwise uses the
first model facet.}

\item{equivalence_bound}{Practical-equivalence bound in logits. Default
\code{0.5} is a moderate bound intended as a starting point, not a
universal threshold. The TOST/ROPE result depends on both the bound
\emph{and} the per-level standard errors, so in small or high-variance
designs the test may fail to reject non-equivalence simply because
the SEs are wide. Choose \code{equivalence_bound} based on the smallest
difference that would be practically meaningful in your assessment
context (commonly 0.3 to 0.5 logits for rater-mediated designs) and
check \verb{$summary} for per-level SE magnitude before drawing
conclusions.}

\item{ci_level}{Confidence level used for the forest-style interval
view. Default \code{0.95}.}

\item{conf_level}{Deprecated alias for \code{ci_level}, retained for
backward compatibility. Supplying a non-\code{NULL} value overrides
\code{ci_level} and emits a one-time deprecation warning. Will be
removed in a future release.
Default \code{0.95}.}
}
\value{
A named list with class \code{mfrm_facet_equivalence}.
}
\description{
Analyze practical equivalence within a facet
}
\details{
This function tests whether facet elements (e.g., raters) are similar
enough to be treated as practically interchangeable, rather than merely
testing whether they differ significantly.  This is the key distinction
from a standard chi-square heterogeneity test: absence of evidence
for difference is not evidence of equivalence.

The function uses existing facet estimates and their standard errors
from \code{diagnostics$measures}; no re-estimation is performed.

The bundle combines four complementary views:
\enumerate{
\item \strong{Fixed chi-square test}: tests \eqn{H_0}: all element measures
are equal.  A non-significant result is \emph{necessary but not
sufficient} for interchangeability. It is reported as context, not
as direct evidence of equivalence.
\item \strong{Pairwise TOST (Two One-Sided Tests)}: for each pair of
elements, tests whether the difference falls within
\eqn{\pm}\code{equivalence_bound}.  The TOST procedure (Schuirmann,
1987) rejects the null hypothesis of \emph{non-equivalence} when both
one-sided tests are significant at level \eqn{\alpha}.  A pair is
declared "Equivalent" when the TOST p-value < 0.05.
\item \strong{BIC-based Bayes-factor heuristic}: an approximate screening
tool (not full Bayesian inference) that compares the evidence for
a common-facet model (all elements equal) against a heterogeneity
model (elements differ) via
\eqn{\mathrm{BF}_{01} \approx \exp((\mathrm{BIC}_{H_1} -
   \mathrm{BIC}_{H_0}) / 2)} (Kass & Raftery, 1995).  Values > 3
favour the common-facet model; < 1/3 favour heterogeneity.
\item \strong{ROPE-style grand-mean proximity}: the proportion of each
element's normal-approximation confidence distribution that falls
within \eqn{\pm}\code{equivalence_bound} of the weighted grand mean.
This is a descriptive proximity summary, not a Bayesian ROPE
decision rule around a prespecified null value.
}

\strong{Choosing \code{equivalence_bound}}: the default of 0.5 logits is a
moderate criterion.  For high-stakes certification, 0.3 logits may
be appropriate; for exploratory or low-stakes contexts, 1.0 logits
may suffice.  The bound should reflect the smallest difference that
would be practically meaningful in your application.
}
\section{What this analysis means}{

\code{analyze_facet_equivalence()} is a practical-interchangeability screen. It
asks whether facet levels are close enough, under a user-defined logit
bound, to be treated as practically similar for the current use case.
}

\section{What this analysis does not justify}{

\itemize{
\item A non-significant chi-square result is not evidence of equivalence.
\item Forest/ROPE displays are descriptive and do not replace the pairwise TOST
decision rule.
\item The BIC-based Bayes-factor summary is a heuristic screen, not a full
Bayesian equivalence analysis.
}
}

\section{Interpreting output}{

Start with \code{summary$Decision}, which is a conservative summary of the
pairwise TOST results. Then use the remaining tables as context:
\itemize{
\item \code{chi_square}: is there broad heterogeneity in the facet?
\item \code{pairwise}: which specific pairs meet the practical-equivalence bound?
\item \code{rope} / \code{forest}: how close is each level to the facet grand mean?
}

Smaller \code{equivalence_bound} values make the criterion stricter. If the
decision is \code{"partial_pairwise_equivalence"}, that means some pairwise
contrasts satisfy the practical-equivalence bound but not all of them do.
}

\section{Decision rule}{

The final \code{Decision} is a pairwise TOST summary rather than a global
equivalence proof. If all pairwise contrasts satisfy the practical-
equivalence bound, the facet is labeled \code{"all_pairs_equivalent"}. If at
least one, but not all, pairwise contrasts are equivalent, the facet is
labeled \code{"partial_pairwise_equivalence"}. If no pairwise contrasts meet the
practical-equivalence bound, the facet is labeled
\code{"no_pairwise_equivalence_established"}. The chi-square, Bayes-factor, and
grand-mean proximity summaries are reported as descriptive context.
}

\section{How to read the main outputs}{

\itemize{
\item \code{summary}: one-row pairwise-TOST decision summary and aggregate context.
\item \code{pairwise}: pair-level TOST detail; use this for the primary inferential
read.
\item \code{chi_square}: broad heterogeneity screen.
\item \code{rope} / \code{forest}: level-wise proximity to the weighted grand mean.
}
}

\section{Recommended next step}{

If the result is borderline or high-stakes, re-run the analysis with a
tighter or looser \code{equivalence_bound}, then inspect \code{pairwise} and
\code{\link[=plot_facet_equivalence]{plot_facet_equivalence()}} before deciding how strongly to claim
interchangeability.
}

\section{Typical workflow}{

\enumerate{
\item Fit a model with \code{\link[=fit_mfrm]{fit_mfrm()}}.
\item Run \code{analyze_facet_equivalence()} for the facet you want to screen.
\item Read \code{summary} and \code{chi_square} first.
\item Use \code{\link[=plot_facet_equivalence]{plot_facet_equivalence()}} to inspect which levels drive the result.
}
}

\section{Output}{

The returned bundle has class \code{mfrm_facet_equivalence} and includes:
\itemize{
\item \code{summary}: one-row overview with convergent decision
\item \code{chi_square}: fixed chi-square / separation summary
\item \code{pairwise}: pairwise TOST detail table
\item \code{rope}: element-wise ROPE probabilities around the weighted grand mean
\item \code{forest}: element-wise estimate, confidence interval, and ROPE status
\item \code{settings}: applied facet and threshold settings
}
}

\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")
eq$summary[, c("Facet", "Elements", "Decision", "MeanROPE")]
head(eq$pairwise[, c("ElementA", "ElementB", "Equivalent")])
}
\references{
Kass, R. E., & Raftery, A. E. (1995). Bayes factors. \emph{Journal of the
American Statistical Association, 90}(430), 773-795.

Schuirmann, D. J. (1987). A comparison of the two one-sided tests
procedure and the power approach for assessing the equivalence of
average bioavailability. \emph{Journal of Pharmacokinetics and
Biopharmaceutics, 15}(6), 657-680.
}
\seealso{
\code{\link[=facets_chisq_table]{facets_chisq_table()}}, \code{\link[=fair_average_table]{fair_average_table()}}, \code{\link[=plot_facet_equivalence]{plot_facet_equivalence()}}
}
\concept{confidence intervals}
\concept{facet equivalence}
\concept{reporting workflow}
