% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/certainty.R
\name{certainty}
\alias{certainty}
\title{Analytic certainty of network edges (Bayesian Dirichlet-Multinomial)}
\usage{
certainty(
  x,
  prior = 0.5,
  ci_level = 0.05,
  inference = c("stability", "threshold"),
  consistency_range = c(0.75, 1.25),
  edge_threshold = NULL
)
}
\arguments{
\item{x}{A \code{netobject} from \code{\link{build_network}} using a
transition-probability method (\code{"relative"} / \code{"tna"}), or a
\code{netobject_group}.}

\item{prior}{Numeric. Dirichlet prior concentration added to every cell
(default \code{0.5}, the Jeffreys prior).}

\item{ci_level}{Numeric in (0,1). Tail level for credible intervals and the
stability decision (default \code{0.05}, i.e. a 95\\% interval). Named to
match \code{bootstrap_network()}.}

\item{inference}{Character. \code{"stability"} (default) tests whether the
posterior keeps the edge within a multiplicative \code{consistency_range}
of its weight; \code{"threshold"} tests whether the edge exceeds
\code{edge_threshold}.}

\item{consistency_range}{Numeric vector of length 2. Multiplicative bounds
for stability inference (default \code{c(0.75, 1.25)}).}

\item{edge_threshold}{Numeric or NULL. Fixed threshold for
\code{inference = "threshold"}. If NULL, defaults to the 10th percentile of
non-zero edge weights.}
}
\value{
An object of class \code{c("net_certainty", "net_bootstrap")} with the
same fields as \code{\link{bootstrap_network}}: \code{original}, \code{mean},
\code{sd}, \code{p_values}, \code{significant}, \code{ci_lower},
\code{ci_upper}, \code{cr_lower}, \code{cr_upper}, \code{summary},
\code{model}, \code{method}, \code{params}, \code{ci_level},
\code{inference}, \code{consistency_range}, \code{edge_threshold}, plus
\code{prior} and \code{iter = NA} (no iterations).
}
\description{
Closed-form alternative to \code{\link{bootstrap_network}} for transition
networks. Models the outgoing transitions from each state as a
Dirichlet-Multinomial process: with a Jeffreys prior the posterior for state
\eqn{i} is \eqn{\mathrm{Dirichlet}(c_i + \mathrm{prior})}, so each edge is
marginally Beta and its posterior mean, standard deviation, credible interval
and stability decision are available analytically. No resampling, so it runs
in microseconds.

The return value has the same structure as \code{\link{bootstrap_network}}
(same slots and summary columns) and carries class \code{c("net_certainty",
"net_bootstrap")}, so \code{summary()} and any code that consumes a
\code{net_bootstrap} object work unchanged.
}
\details{
Certainty (this function), stability (\code{\link{bootstrap_network}}) and
reliability (\code{\link[=network_reliability]{reliability}}) answer different questions about an
edge: how precisely it is pinned down by the observed counts, whether it
survives resampling the sequences, and whether it is consistent across
split-halves. Certainty and stability agree on homogeneous data; certainty is
over-confident when the data are a mixture of latent classes, because it
treats transitions clustered within a sequence as independent.
}
\examples{
seqs <- data.frame(V1 = c("A","B","A","C","B"), V2 = c("B","C","B","A","C"),
                   V3 = c("C","A","C","B","A"))
net <- build_network(seqs, method = "relative")
cert <- certainty(net)
cert
summary(cert)

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