% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/def_gof.R
\name{def.gof}
\alias{def.gof}
\title{Directed Ebrahim-Farrington (DEF) Goodness-of-Fit Test}
\usage{
def.gof(
  object,
  predicted_probs = NULL,
  X = NULL,
  G = 10,
  basis = c("poly3", "poly2", "stukel", "ensemble"),
  method = c("satterthwaite", "imhof")
)
}
\arguments{
\item{object}{A fitted binary logistic \code{\link[stats]{glm}}, or a binary
(0/1) response vector \code{y} (then supply \code{predicted_probs}).}

\item{predicted_probs}{Numeric predicted probabilities; required when
\code{object} is a \code{y} vector, ignored when it is a glm.}

\item{X}{Optional design matrix, used only with the \code{y}/\code{predicted_probs}
form: it enables the exact estimation-adjusted (\eqn{\Omega}) calibration
(logit working weights assumed). Without it the conservative \eqn{\chi^2_k}
reference is used and a warning is issued. Ignored when \code{object} is a glm.}

\item{G}{Integer number of equal-frequency groups (default 10; must be >= 3).}

\item{basis}{One of \code{"poly3"} (default), \code{"poly2"}, \code{"stukel"},
or \code{"ensemble"}.}

\item{method}{One of \code{"satterthwaite"} (default) or \code{"imhof"}.}
}
\value{
A one-row \code{data.frame} with columns \code{Test}, \code{Basis},
  \code{Test_Statistic} (the statistic \eqn{S}), \code{df}, \code{Method}, and
  \code{p_value}. When \code{basis = "ensemble"}, the return is that of
  \code{\link{def.ensemble.gof}}.
}
\description{
Performs the Directed Ebrahim-Farrington (DEF) goodness-of-fit test for a
fitted binary logistic regression model. DEF concentrates its power on a small
set of calibration-curve "shape" directions by projecting the grouped
standardized residuals onto a low-dimensional basis and testing the squared
length of that projection.
}
\details{
The observations are sorted by predicted probability and split into \code{G}
equal-frequency groups; the standardized grouped residual vector \eqn{r} is
projected onto a basis matrix \eqn{Z} of smooth shapes, giving
\eqn{S = (Z'r)'(Z'Z)^{-1}(Z'r)}. Its null distribution is a weighted sum of
\eqn{\chi^2_1} variables with weights equal to the eigenvalues of
\eqn{(Z'Z)^{-1}Z'\Omega Z}, where \eqn{\Omega = I - U(X'WX)^{-1}U'} is the
estimation-adjusted covariance of the grouped residuals. The p-value uses a
Satterthwaite scaled-\eqn{\chi^2} approximation (default) or Imhof's method
(if the \pkg{CompQuadForm} package is installed). Bases: \code{"poly2"},
\code{"poly3"} (default), \code{"stukel"}; \code{"ensemble"} runs all three and
combines them via \code{\link{def.ensemble.gof}}.
}
\examples{
set.seed(1)
n <- 500
x <- runif(n, -3, 3)
y <- rbinom(n, 1, 1 / (1 + exp(-(0.6 * x))))
fit <- glm(y ~ x, family = binomial())
def.gof(fit)                       # default poly3 basis
def.gof(fit, basis = "stukel")     # tail-shape basis
def.gof(fit, basis = "ensemble")   # combine all three (CCT)

}
\references{
Ebrahim, K. E. and El-Kotory, A. Omnibus versus Directed Goodness-of-Fit Tests
for Sparse Data in Binary Logistic Regression (companion paper).
}
\seealso{
\code{\link{ef.gof}}, \code{\link{def.ensemble.gof}}.
}
\author{
Ebrahim Khaled Ebrahim \email{ebrahimkhaled@alexu.edu.eg}
}
