% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence_compare.R
\name{sequence_compare}
\alias{sequence_compare}
\title{Compare Subsequence Patterns Between Groups}
\usage{
sequence_compare(
  x,
  group = NULL,
  sub = 3:5,
  min_freq = 5L,
  test = c("permutation", "chisq", "none"),
  iter = 1000L,
  adjust = "fdr"
)
}
\arguments{
\item{x}{A \code{netobject_group} (from grouped \code{build_network}),
a \code{netobject} (requires \code{group}), or a wide-format
\code{data.frame} (requires \code{group}).}

\item{group}{Character or vector. Column name or vector of group labels.
Not needed for \code{netobject_group}.}

\item{sub}{Integer vector. Pattern lengths to analyze. Default: \code{3:5}.}

\item{min_freq}{Integer. Minimum frequency in each group for a pattern
to be included. Default: 5.}

\item{test}{Character. Inference method: one of \code{"permutation"}
(default), \code{"chisq"}, or \code{"none"}. See Details.}

\item{iter}{Integer. Permutation iterations. Only used when
\code{test = "permutation"}. Default: 1000.}

\item{adjust}{Character. P-value correction method (see
\code{\link[stats]{p.adjust}}). Default: \code{"fdr"}.}
}
\value{
An object of class \code{"net_sequence_comparison"} containing:
\describe{
\item{patterns}{Tidy data.frame. Always present:
\code{pattern}, \code{length}, \code{freq_<group>},
\code{prop_<group>}, \code{resid_<group>}. If
\code{test = "permutation"}: \code{effect_size}, \code{p_value}.
If \code{test = "chisq"}: \code{statistic}, \code{p_value}.}
\item{groups}{Character vector of group names.}
\item{n_patterns}{Integer. Number of patterns passing min_freq.}
\item{params}{List of sub, min_freq, test, iter, adjust.}
}
}
\description{
Extracts all k-gram patterns (subsequences of length k) from sequences
in each group, computes standardized residuals against the independence
model, and optionally runs a permutation or chi-square test of
group differences.
}
\details{
Standardized residuals are always computed from a 2xG contingency table
of (this pattern vs. everything else) using the textbook formula
\code{(o - e) / sqrt(e * (1 - r/N) * (1 - c/N))}. They describe how much
each group's count for a given pattern deviates from expectation under
independence, scaled to be approximately N(0,1) under the null.

The optional \code{test} argument chooses an inference method:
\describe{
\item{\code{"permutation"}}{Shuffles group labels across sequences and
recomputes a per-pattern statistic (row-wise Euclidean residual norm).
Answers: "is this pattern's distribution associated with group
membership at the \emph{actor} level?" Respects the sequence as the
unit of analysis; can be underpowered when the number of sequences
is small.}
\item{\code{"chisq"}}{Runs \code{chisq.test} on the 2xG table per
pattern. Answers: "do the group \emph{streams} generate this pattern
at different rates?" Treats each k-gram occurrence as an event; fast
and powerful even with few sequences, but the iid assumption it makes
is optimistic when sequences are strongly autocorrelated.}
\item{\code{"none"}}{Skip inference. Only residuals, frequencies, and
proportions are returned.}
}

P-values are adjusted once across all patterns (not per-pattern) using
any method supported by \code{\link[stats]{p.adjust}}. The default is
\code{"fdr"} (Benjamini-Hochberg).
}
\examples{
seqs <- data.frame(
  V1 = sample(LETTERS[1:4], 60, TRUE),
  V2 = sample(LETTERS[1:4], 60, TRUE),
  V3 = sample(LETTERS[1:4], 60, TRUE),
  V4 = sample(LETTERS[1:4], 60, TRUE)
)
grp <- rep(c("X", "Y"), 30)
net <- build_network(seqs, method = "relative")
res <- sequence_compare(net, group = grp, sub = 2:3, test = "chisq")

}
