% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/assoc.R
\name{uncertainty_coef}
\alias{uncertainty_coef}
\title{Uncertainty Coefficient}
\usage{
uncertainty_coef(
  x,
  direction = c("symmetric", "row", "column"),
  detail = FALSE,
  conf_level = 0.95,
  digits = 3L,
  .include_se = FALSE
)
}
\arguments{
\item{x}{A contingency table (of class \code{table}).}

\item{direction}{Direction of prediction:
\code{"symmetric"} (default), \code{"row"} (column predicts row),
or \code{"column"} (row predicts column).}

\item{detail}{Logical. If \code{FALSE} (default), return the estimate
as a numeric scalar. If \code{TRUE}, return a named numeric vector
including confidence interval and p-value.}

\item{conf_level}{A number between 0 and 1 giving the confidence
level (default \code{0.95}). Only used when \code{detail = TRUE}. Set
to \code{NULL} to omit the confidence interval.}

\item{digits}{Number of decimal places used when printing the
result (default \code{3}). Only affects the \code{detail = TRUE} output.}

\item{.include_se}{Internal parameter; do not use.}
}
\value{
Same structure as \code{\link[=cramer_v]{cramer_v()}}: a scalar when
\code{detail = FALSE}, a named vector when \code{detail = TRUE}.
The p-value tests H0: U = 0 (Wald z-test).
}
\description{
\code{uncertainty_coef()} computes the Uncertainty Coefficient
(Theil's U) for a two-way contingency table, based on
information entropy.
}
\details{
The uncertainty coefficient measures association using
Shannon entropy.
For \code{direction = "row"}:
\eqn{U = (H_X + H_Y - H_{XY}) / H_X}, where \eqn{H_X},
\eqn{H_Y} are the marginal entropies and \eqn{H_{XY}} is
the joint entropy.
The symmetric version is
\eqn{U = 2 (H_X + H_Y - H_{XY}) / (H_X + H_Y)}.
Standard error formulas follow the DescTools implementations
(Signorell et al., 2024); see \code{\link[=cramer_v]{cramer_v()}} for full references.
}
\examples{
tab <- table(sochealth$smoking, sochealth$education)
uncertainty_coef(tab)
uncertainty_coef(tab, direction = "row", detail = TRUE)

}
\seealso{
\code{\link[=lambda_gk]{lambda_gk()}}, \code{\link[=goodman_kruskal_tau]{goodman_kruskal_tau()}}, \code{\link[=assoc_measures]{assoc_measures()}}
}
