% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/path_dependence.R
\name{path_dependence}
\alias{path_dependence}
\title{Per-Context Path Dependence at Order k}
\usage{
path_dependence(x, order = 2L, min_count = 5L, base = 2)
}
\arguments{
\item{x}{A wide sequence data.frame / matrix (rows = actors, columns =
time-steps), or a \code{netobject} that carries the source data.}

\item{order}{Integer. Order of the conditioning context. \code{order = 2}
(default) compares 2-step memory against 1-step; \code{order = 3}
compares 3-step memory; etc. Must be a whole number; a non-integer
value is an error rather than being silently truncated.}

\item{min_count}{Integer. Drop contexts seen fewer than this many times.
Default 5. Very small samples produce noisy KL estimates.}

\item{base}{Numeric. Logarithm base for entropy and KL. Default 2 (bits).}
}
\value{
An object of class \code{"net_path_dependence"} with
\describe{
\item{contexts}{tidy data.frame, one row per order-k context, sorted
by KL descending. Columns: \code{context} (e.g. "A -> B"), \code{n}
(count), \code{H_order1} (entropy of \eqn{P(\cdot \mid s_{k-1})}),
\code{H_orderk} (entropy of \eqn{P(\cdot \mid \mathrm{context})}),
\code{H_drop} (= \code{H_order1} - \code{H_orderk}), \code{KL}
(= \eqn{D_{KL}(P_k \| P_1)}), \code{top_o1} (most likely next state
under order-1), \code{top_ok} (most likely next state under order-k),
\code{flips} (logical: did the most likely next state change?).}
\item{chain}{list with chain-level summaries: \code{KL_weighted}
(count-weighted mean KL across contexts), \code{H_drop_weighted}
(count-weighted mean entropy drop), \code{n_contexts}, \code{n_flips}
(contexts where the most-likely next state changed).}
\item{order}{integer}
\item{base}{numeric}
\item{min_count}{integer}
\item{states}{character vector}
}
}
\description{
Diagnoses where a chain's order-1 Markov assumption fails by comparing,
for each order-k context \eqn{(s_1, \ldots, s_{k-1})}, the empirical
next-state distribution \eqn{P(s_k \mid s_1, \ldots, s_{k-1})} against
the order-1 prediction \eqn{P(s_k \mid s_{k-1})} that uses only the most
recent state. Returns a tidy per-context table sorted by Kullback-Leibler
divergence so the analyst can see exactly \emph{which} histories carry extra
predictive information.
}
\details{
For each context \eqn{c = (s_1, \ldots, s_{k-1})} occurring at least
\code{min_count} times, the function computes:
\itemize{
\item the empirical conditional \eqn{P_k(\cdot \mid c)} from k-gram counts;
\item the order-1 prediction \eqn{P_1(\cdot \mid s_{k-1})} from the
most recent state alone (the bigram-marginal estimator);
\item the entropy drop \eqn{H(P_1) - H(P_k)} - bits of uncertainty
removed by extending memory by one step in this specific context;
\item the Kullback-Leibler divergence \eqn{D_{KL}(P_k \,\|\, P_1)} -
bits of "surprise" if you used the order-1 model when the order-k
model is true.
}

\code{KL = 0} means longer history adds no information for that context.
\code{H_drop > 0} means longer history sharpens the prediction;
\code{H_drop < 0} indicates the order-k context happens to spread
probability across more outcomes than order-1 alone (small-sample noise
or genuine context-induced uncertainty - inspect \code{n}).

Contexts where \code{flips = TRUE} are the substantively interesting
ones: the longer history changes the \emph{modal} prediction, not just its
confidence.

Pair this with \code{\link{markov_order_test}} (which decides whether
order-k is needed \emph{globally}) to see the chain-level decision broken
down per context.
}
\examples{
\donttest{
data(trajectories, package = "Nestimate")
pd <- path_dependence(as.data.frame(trajectories), order = 2)
print(pd)
summary(pd)
plot(pd)
}

}
\references{
Cover, T.M. & Thomas, J.A. (2006). \emph{Elements of Information
Theory}, 2nd ed., chapters 2 and 4. Wiley. (KL divergence and
conditional entropy.)
}
\seealso{
\code{\link{markov_order_test}}, \code{\link{transition_entropy}},
\code{\link{build_mogen}}
}
