% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hwe.R
\name{hwe}
\alias{hwe}
\title{Hardy-Weinberg Equilibrium Test (Multiallelic, Unified Interface)}
\usage{
hwe(
  data,
  type = c("alleles", "genotypes", "counts"),
  verbose = TRUE,
  yates.correct = FALSE,
  B = 1e+05,
  seed = 123
)
}
\arguments{
\item{data}{genotype data in one of three formats:
\itemize{
\item alleles two-column allele pairs
\item genotypes integer genotype IDs (triangular encoding)
\item counts symmetric genotype count matrix
}}

\item{type}{input format: "alleles", "genotypes", or "counts"}

\item{verbose}{logical; if TRUE, prints full test output}

\item{yates.correct}{logical; if TRUE applies Yates continuity correction
to Pearson chi-square statistic only}

\item{B}{number of Monte Carlo replicates for exact test}

\item{seed}{random seed for Monte Carlo exact test}
}
\value{
Named list containing:
\itemize{
\item \code{source} — input representation used ("alleles", "genotypes", or "counts")
\item \code{X2} — Pearson chi-square statistic
\item \code{p_X2} — asymptotic p-value of Pearson chi-square test
\item \code{LRT} — likelihood ratio statistic
\item \code{p_LRT} — asymptotic p-value of likelihood ratio test
\item \code{p_exact} — Monte Carlo exact test p-value
\item \code{freq} — allele frequency vector
\item \code{rho} — inbreeding coefficient
}
}
\description{
Unified Hardy-Weinberg equilibrium (HWE) testing procedure for multiallelic loci.
All input formats are internally converted to a single genotype count matrix,
ensuring identical inference across representations.
}
\details{
Let allele frequencies be:
\deqn{p_i = \frac{c_i}{2n}}

Under Hardy–Weinberg equilibrium:
\deqn{
P_{ii} = p_i^2,\quad P_{ij} = 2p_i p_j \ (i \ne j)
}

Expected genotype counts:
\deqn{E_{ij} = n P_{ij}}

All input formats are mapped to the same genotype matrix,
ensuring algebraic equivalence.

\emph{Pearson chi-square}
\deqn{
X^2 = \sum_{i \le j} \frac{(O_{ij} - E_{ij})^2}{E_{ij}}
}

With optional Yates correction:
\deqn{
X^2 = \sum \frac{(|O_{ij} - E_{ij}| - 0.5)^2}{E_{ij}}
}

\emph{Likelihood ratio test}
\deqn{
G^2 = 2 \sum_{i \le j} O_{ij} \log(O_{ij}/E_{ij})
}

with convention 0log(0) = 0.

\emph{Inbreeding coefficient}
\deqn{
F = \frac{H_{obs} - H_{exp}}{1 - H_{exp}}
}
where:
\deqn{
H_{obs} = \sum_i O_{ii}/n,\quad H_{exp} = \sum_i p_i^2
}

Under:
\deqn{X \sim \text{Multinomial}(n, P)}

the p-value is:
\deqn{
p = \Pr(\ell(X^{sim}) \le \ell(X^{obs}))
}
where:
\deqn{
\ell(x) = \sum x_i \log p_i + \log \frac{n!}{\prod x_i!}
}

\deqn{
\text{alleles} \equiv \text{genotype IDs} \equiv \text{count matrix}
\rightarrow M_{ij}
}

Hence all statistics are identical up to Monte Carlo variation.
}
\note{
Note that
\itemize{
\item Zero-frequency alleles are removed automatically
\item Exact test is Monte Carlo (fixed seed for reproducibility)
\item All statistics are computed on the same standardized genotype matrix
}
}
\examples{
\dontrun{
a1 <- c(1,1,1,1,2,2,2,3,3,1,2,3,1,2,3,1,2,3)
a2 <- c(1,2,3,1,2,3,2,3,1,2,3,1,1,1,2,3,2,3)
r1 <- hwe(cbind(a1,a2), "alleles", FALSE)
g <- a2g(a1,a2)
r2 <- hwe(g, "genotypes", FALSE)
g_tab <- table(g)
pairs <- g2a(as.integer(names(g_tab)))
k <- max(pairs)
M <- matrix(0, k, k)
for(i in seq_len(nrow(pairs))) {
  M[pairs[i,1], pairs[i,2]] <- g_tab[i]
}
r3 <- hwe(M, "counts", FALSE)
r <- lapply(list(r1, r2, r3), \(x) within(as.data.frame(x), {
     freq <- paste(round(as.numeric(freq), 3), collapse=";")})[1,])
do.call(rbind,r)
}
}
