% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bayes_compare.R
\name{bayes_compare}
\alias{bayes_compare}
\title{Bayesian Dirichlet-Multinomial comparison of two transition networks}
\usage{
bayes_compare(
  x,
  y = NULL,
  prior = 0.5,
  draws = 10000L,
  ci = 0.95,
  mean_threshold = 0.01,
  bound_threshold = 0.001,
  seed = NULL
)
}
\arguments{
\item{x}{A \code{netobject} (from \code{\link{build_network}}), a
\code{netobject_group}, an \code{mcml} object, or a
\code{\link{net_edge_betweenness}} object. Must use a transition
method (\code{"relative"} / \code{"frequency"} and their aliases).}

\item{y}{A second object of the same kind as \code{x}, or \code{NULL}.
When \code{x} is a \code{netobject_group} and \code{y} is \code{NULL},
all pairwise comparisons among the groups are returned.}

\item{prior}{Numeric. Dirichlet prior concentration added to every cell
(default \code{0.5}, the Jeffreys prior). Use \code{1} for a uniform
(Laplace) prior.}

\item{draws}{Integer. Number of Monte Carlo posterior draws used for the
credible intervals (default \code{10000}).}

\item{ci}{Numeric in (0, 1). Credible interval mass (default \code{0.95}).}

\item{mean_threshold}{Numeric. An edge is flagged significant only if the
absolute posterior mean difference exceeds this (default \code{0.01}).}

\item{bound_threshold}{Numeric. An edge is flagged significant only if the
credible-interval bound nearest zero exceeds this in absolute value
(default \code{0.001}). Guards against differences that are detectable
but negligibly small.}

\item{seed}{Integer or NULL. RNG seed for reproducible credible intervals.}
}
\value{
An object of class
\code{c("net_bayes", "netdifference", "net_permutation")}. It carries
the same fields as a \code{\link{permutation}} result, so it is a drop-in
wherever a \code{net_permutation} is consumed, and also carries a
\code{netdifference} difference matrix for cograph difference plotting,
plus Bayesian extras:
\describe{
\item{x, y}{The two input \code{netobject}s.}
\item{diff}{Posterior mean difference matrix (\code{prob_x - prob_y});
the analogue of the permutation observed difference.}
\item{difference_matrix}{Alias of \code{diff} for cograph
\code{netdifference} helpers.}
\item{diff_sig}{Difference where \code{sig}, else 0.}
\item{p_values}{P-value matrix (the two-sided Bayesian p-equivalent).}
\item{effect_size}{Posterior mean difference over its posterior SD.}
\item{ci_lower, ci_upper}{Credible-interval bound matrices.}
\item{p_difference}{Probability of the difference: the share of
posterior mass on the dominant side of zero, in \eqn{[0.5, 1]}
(\eqn{P(\mathrm{High} > \mathrm{Low})} for a positive difference).}
\item{p_bayes}{Alias of \code{p_values} (two-sided Bayesian p,
\eqn{2(1-\mathrm{p\_difference})}).}
\item{prob_x, prob_y}{Posterior mean transition-probability matrices.}
\item{sig}{Logical significance matrix (CI excludes zero, mean and
nearest bound exceed their thresholds).}
\item{summary}{Long-format data frame whose columns are a superset of
\code{summary.net_permutation} (\code{from, to, weight_x, weight_y, diff,
    effect_size, p_value, sig}) plus \code{count_x, count_y, ci_lower,
    ci_upper, ci_width, p_difference}.}
\item{method, iter, alpha, paired, adjust}{Permutation-compatible settings
(\code{iter = draws}, \code{alpha = 1 - ci}, \code{paired = FALSE},
\code{adjust = "none"}).}
\item{prior, draws, ci, mean_threshold, bound_threshold}{Bayesian settings.}
}
}
\description{
Compares two transition networks estimated by \code{\link{build_network}}
(method \code{"relative"} or \code{"frequency"}) using a Bayesian
Dirichlet-Multinomial model. The outgoing transitions from each source
state are modelled as a Multinomial draw with a Dirichlet prior on the
transition probabilities. With a Jeffreys prior the posterior for the
transitions out of state \eqn{i} is \eqn{\mathrm{Dirichlet}(c_i + \alpha)},
where \eqn{c_i} are the observed outgoing counts. Each edge probability is
then marginally Beta-distributed, so the posterior mean difference between
the two networks is available in closed form and a credible interval is
obtained by Monte Carlo.

This is a complement to \code{\link{permutation}}: the permutation test
answers "is this difference more extreme than chance?"; the Bayesian
comparison answers "what is the plausible range of the true difference,
and how precisely is it estimated given the counts?". An edge with few
outgoing transitions from its source state yields a wide credible
interval even when its row-normalised probability looks decisive.

\code{bayes_compare()} also accepts two \code{\link{net_edge_betweenness}}
objects (source method \code{"relative"} only). Edge betweenness is a
nonlinear function of the whole transition matrix, so instead of Beta
marginals the full transition matrix is drawn from each group's row-wise
Dirichlet posterior and edge betweenness is recomputed on every draw -
the Bayesian analogue of \code{permutation()}'s edge-betweenness dispatch.
The result summarises the posterior of \code{EB(x) - EB(y)}: \code{diff}
is the posterior mean difference, \code{prob_x}/\code{prob_y} hold the
posterior mean betweenness matrices, and \code{observed_diff} the plug-in
difference of the two input networks. Both inputs must use the same
\code{invert} setting.
}
\examples{
s1 <- data.frame(V1 = c("A","B","C"), V2 = c("B","C","A"))
s2 <- data.frame(V1 = c("A","C","B"), V2 = c("C","B","A"))
n1 <- build_network(s1, method = "relative")
n2 <- build_network(s2, method = "relative")
bayes_compare(n1, n2, draws = 500, seed = 1)

}
\references{
Johnston, L. & Jendoubi, T. (2026). How Delivery Mode Reshapes Resource
Engagement: A Bayesian Differential Network Analysis. TNA Workshop 2026.

Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, A., &
Rubin, D. B. (2013). \emph{Bayesian Data Analysis} (3rd ed.). CRC Press.

Jeffreys, H. (1946). An invariant form for the prior probability in
estimation problems. \emph{Proceedings of the Royal Society of London A},
186(1007), 453-461.
}
\seealso{
\code{\link{permutation}} for the frequentist complement;
\code{\link{certainty}} for single-network posterior edge intervals;
\code{\link{subtract_networks}} and \code{\link{as_netdifference}} for the
difference verbs; \code{\link{build_network}}
}
