% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hypa.R
\name{build_hypa}
\alias{build_hypa}
\title{Detect Path Anomalies via HYPA}
\usage{
build_hypa(data, k = 3L, alpha = 0.05, min_count = 5L, p_adjust = "BH")
}
\arguments{
\item{data}{A data.frame (rows = trajectories), list of character vectors,
\code{tna} object, or \code{netobject} with sequence data. For
\code{tna}/\code{netobject}, numeric state IDs are automatically
converted to label names.}

\item{k}{Integer. Order of the De Bruijn graph (default 2). Detects
anomalies in paths of length k.}

\item{alpha}{Numeric. Significance threshold for anomaly classification
(default 0.05). Paths with HYPA score < alpha are under-represented;
paths with score > 1-alpha are over-represented.}

\item{min_count}{Integer. Minimum observed count for a path to be
classified as anomalous (default 2). Paths with fewer observations
are always classified as \code{"normal"} regardless of their
HYPA score, since single occurrences are unreliable.}

\item{p_adjust}{Character. Method for multiple testing correction of
p-values. Default \code{"BH"} (Benjamini-Hochberg FDR control).
Accepts any method from \code{\link[stats]{p.adjust.methods}} or
\code{"none"} to skip correction. Under- and over-representation
p-values are adjusted separately (two-sided testing).}
}
\value{
An object of class \code{net_hypa} with components:
\describe{
\item{scores}{Data frame with path, from, to, observed, expected,
ratio, p_value, p_adjusted_under, p_adjusted_over, anomaly
columns. The \code{path} column shows the full state sequence
(e.g., "A -> B -> C"); \code{from} is the context (conditioning
states); \code{to} is the next state; \code{ratio} is
observed / expected; \code{p_value} is the raw hypergeometric
CDF value; \code{p_adjusted_under} and \code{p_adjusted_over}
are the corrected p-values for under- and over-representation
tests respectively.}
\item{adjacency}{Weighted adjacency matrix of the De Bruijn graph.}
\item{xi}{Fitted propensity matrix.}
\item{k}{Order of the De Bruijn graph.}
\item{alpha}{Significance threshold used.}
\item{p_adjust}{Multiple testing correction method used.}
\item{n_anomalous}{Number of anomalous paths detected.}
\item{n_over}{Number of over-represented paths.}
\item{n_under}{Number of under-represented paths.}
\item{n_edges}{Total number of edges.}
\item{nodes}{Node names in the De Bruijn graph.}
}
}
\description{
Constructs a k-th order De Bruijn graph from sequential trajectory data and
uses a hypergeometric null model to detect paths with anomalous frequencies.
Paths occurring more or less often than expected under the null model are
flagged as over- or under-represented.
}
\examples{
seqs <- list(c("A","B","C"), c("B","C","A"), c("A","C","B"), c("A","B","C"))
hyp <- build_hypa(seqs, k = 2)

\donttest{
trajs <- list(c("A","B","C"), c("A","B","C"), c("A","B","C"),
              c("A","B","D"), c("C","B","D"), c("C","B","A"))
h <- build_hypa(trajs, k = 2)
print(h)
}

}
\references{
LaRock, T., Nanumyan, V., Scholtes, I., Casiraghi, G., Eliassi-Rad, T.,
& Schweitzer, F. (2020). HYPA: Efficient Detection of Path Anomalies in
Time Series Data on Networks. \emph{SDM 2020}, 460–468.
}
