% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hon.R
\name{build_hon}
\alias{build_hon}
\title{Build a Higher-Order Network (HON)}
\usage{
build_hon(
  data,
  max_order = 5L,
  min_freq = 1L,
  collapse_repeats = FALSE,
  method = "hon+"
)
}
\arguments{
\item{data}{One of:
\itemize{
\item \code{data.frame}: rows are trajectories, columns are time steps.
Trailing \code{NA}s are stripped. All non-NA values are coerced to
character.
\item \code{list}: each element is a character (or coercible) vector
representing one trajectory.
\item \code{tna}: a tna object with sequence data. Numeric state
IDs are automatically converted to label names.
\item \code{netobject}: a netobject with sequence data.
}}

\item{max_order}{Integer. Maximum order of the HON. Default 5.
The algorithm may produce lower-order nodes if the data do not
justify higher orders.}

\item{min_freq}{Integer. Minimum frequency for a transition to be
considered. Transitions observed fewer than \code{min_freq} times are
treated as zero. Default 1.}

\item{collapse_repeats}{Logical. If \code{TRUE}, adjacent duplicate states
within each trajectory are collapsed before analysis. Default \code{FALSE}.}

\item{method}{Character. Algorithm to use: \code{"hon+"} (default,
parameter-free BuildHON+ with lazy observation building and MaxDivergence
pruning) or \code{"hon"} (original BuildHON with eager observation
building).}
}
\value{
An S3 object of class \code{"net_hon"} containing:
\describe{
\item{matrix}{Weighted adjacency matrix (rows = from, cols = to).
Rows and columns use readable arrow notation (e.g., \code{"A -> B"}).}
\item{edges}{Data frame with columns: \code{path} (full state sequence,
e.g., "A -> B -> C"), \code{from} (context/conditioning states),
\code{to} (predicted next state), \code{count} (raw frequency),
\code{probability} (transition probability), \code{from_order},
\code{to_order}.}
\item{nodes}{data.frame with columns \code{id}, \code{label},
\code{name} (one row per HON node; \code{label}/\code{name} are the
arrow-notation node names). Stored as a data.frame for
\code{cograph_network} compatibility.}
\item{n_nodes}{Number of HON nodes.}
\item{n_edges}{Number of edges.}
\item{first_order_states}{Character vector of unique original states.}
\item{max_order_requested}{The \code{max_order} parameter used.}
\item{max_order_observed}{Highest order actually present.}
\item{min_freq}{The \code{min_freq} parameter used.}
\item{n_trajectories}{Number of trajectories after parsing.}
\item{directed}{Logical. Always \code{TRUE}.}
}
}
\description{
Constructs a Higher-Order Network from sequential data, faithfully
implementing the BuildHON algorithm (Xu, Wickramarathne & Chawla, 2016).

The algorithm detects when a first-order Markov model is insufficient
to capture sequential dependencies and automatically creates higher-order
nodes. Uses KL-divergence to determine whether extending a node's history
provides significantly different transition distributions.
}
\details{
\strong{Node naming convention}: Higher-order nodes use readable arrow
notation. A first-order node is simply \code{"A"}. A second-order node
representing the context "came from A, now at B" is \code{"A -> B"}.
Third-order: \code{"A -> B -> C"}, etc.

\strong{Algorithm overview}:
\enumerate{
\item Count all subsequence transitions up to \code{max_order + 1}.
\item Build probability distributions, filtering by \code{min_freq}.
\item For each first-order source, recursively test whether extending
the history (adding more context) produces a significantly different
distribution (via KL-divergence vs. an adaptive threshold).
\item Build the network from the accepted rules, rewiring edges so
higher-order nodes are properly connected.
}
}
\examples{
seqs <- list(c("A","B","C","D"), c("A","B","C","A"), c("B","C","D","A"))
hon <- build_hon(seqs, max_order = 2)

\donttest{
# From list of trajectories
trajs <- list(
  c("A", "B", "C", "D", "A"),
  c("A", "B", "D", "C", "A"),
  c("A", "B", "C", "D", "A")
)
hon <- build_hon(trajs, max_order = 3, min_freq = 1)
print(hon)
summary(hon)

# From data.frame (rows = trajectories)
df <- data.frame(T1 = c("A", "A"), T2 = c("B", "B"),
                 T3 = c("C", "D"), T4 = c("D", "C"))
hon <- build_hon(df, max_order = 2)
}

}
\references{
Xu, J., Wickramarathne, T. L., & Chawla, N. V. (2016). Representing
higher-order dependencies in networks. \emph{Science Advances},
2(5), e1600028.

Saebi, M., Xu, J., Kaplan, L. M., Ribeiro, B., & Chawla, N. V. (2020).
Efficient modeling of higher-order dependencies in networks: from algorithm
to application for anomaly detection. \emph{EPJ Data Science}, 9(1), 15.
}
