% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/div_gof.R
\name{div_gof}
\alias{div_gof}
\title{Divergence Tests of Goodness of Fit}
\usage{
div_gof(
  dat,
  var_uniform = NULL,
  var1 = NULL,
  var2 = NULL,
  var_cond = NULL,
  model_full = NULL,
  model_reduced = NULL,
  alpha = 0.05,
  dec = 3,
  use_approx_cv = TRUE
)
}
\arguments{
\item{dat}{dataframe with rows as observations and columns as variables.
Variables must be categorical with finite range spaces.}

\item{var_uniform}{character name of a variable in \code{dat} to test for uniformity.}

\item{var1}{character name of the first variable.}

\item{var2}{character name of the second variable.}

\item{var_cond}{optional character vector of conditioning variables.}

\item{model_full}{list containing \code{D} and \code{df} for the full model.}

\item{model_reduced}{list containing \code{D} and \code{df} for the reduced model.}

\item{alpha}{significance level. Default is 0.05.}

\item{dec}{number of decimals for rounding. Default is 3.}

\item{use_approx_cv}{logical; if \code{TRUE}, uses the approximate critical value
\code{df + sqrt(8 * df)}. If \code{FALSE}, uses the chi-square quantile.}
}
\value{
Dataframe with test type, divergence \emph{D}, chi-square statistic,
degrees of freedom, critical value, and decision.
}
\description{
Performs divergence-based goodness-of-fit tests for discrete data,
including tests of uniformity, pairwise independence, conditional independence,
and nested model comparisons.
}
\details{
The function implements four types of tests:

\strong{1. Uniformity}
\deqn{D = \log r_X - H(X)}

\strong{2. Pairwise Independence}
\deqn{D = H(X) + H(Y) - H(X,Y)}

\strong{3. Conditional Independence}
\deqn{D = H(X,Z) + H(Y,Z) - H(Z) - H(X,Y,Z)}

where \emph{Z} may also represent a vector of conditioning variables.

\strong{4. Nested Model Comparison}
\deqn{D = D_{reduced} - D_{full}}

The test statistic is
\deqn{2nD\log(2),}
since entropies are computed using base 2 logarithms.

Smaller divergence values indicate better model fit.
}
\examples{
data(lawdata)
df_att <- lawdata[[4]]

att_var <- data.frame(
  status    = df_att$status - 1,
  gender    = df_att$gender,
  office    = df_att$office - 1,
  years     = ifelse(df_att$years <= 3, 0,
                ifelse(df_att$years <= 13, 1, 2)),
  age       = ifelse(df_att$age <= 35, 0,
                ifelse(df_att$age <= 45, 1, 2)),
  practice  = df_att$practice,
  lawschool = df_att$lawschool - 1
)

## 1. Test uniformity
div_gof(att_var, var_uniform = "gender")

## 2. Test pairwise independence
div_gof(att_var, var1 = "status", var2 = "gender")

## 3. Test conditional independence

## (a) Conditional independence given a single variable
div_gof(att_var,
        var1 = "status",
        var2 = "gender",
        var_cond = "years")

## (b) Conditional independence given multiple variables
div_gof(att_var,
        var1 = "status",
        var2 = "gender",
        var_cond = c("years", "age"))

## 4. Nested model comparison
## Compare reduced models against the saturated empirical model.
## The saturated model has divergence D = 0 and df = 0.
m_full <- list(D = 0, df = 0)

## (a) Pairwise independence model
m_reduced <- div_gof(att_var,
                    var1 = "status",
                    var2 = "gender")

div_gof(att_var,
        model_full = m_full,
        model_reduced = list(D = m_reduced$D, df = m_reduced$df))

## (b) Conditional independence model
m_reduced <- div_gof(att_var,
                    var1 = "status",
                    var2 = "gender",
                    var_cond = "years")

div_gof(att_var,
        model_full = m_full,
        model_reduced = list(D = m_reduced$D, df = m_reduced$df))

## 5. Nested comparison against the saturated empirical model
m_full <- list(D = 0, df = 0)

m_reduced <- div_gof(att_var,
                    var1 = "status",
                    var2 = "gender")

div_gof(att_var,
        model_full = m_full,
        model_reduced = list(D = m_reduced$D, df = m_reduced$df))
}
\references{
Frank, O., & Shafie, T. (2016). Multivariate entropy analysis of network data.
\emph{Bulletin of Sociological Methodology/Bulletin de Méthodologie Sociologique}, 129(1), 45-63.
}
\seealso{
\code{\link{joint_entropy}}, \code{\link{entropy_trivar}}
}
\author{
Termeh Shafie
}
