% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/breslow_day_test.R
\name{breslow_day_test}
\alias{breslow_day_test}
\alias{print.breslow_day_test}
\title{Breslow-Day Test for Homogeneity of Odds Ratios}
\usage{
breslow_day_test(x, OR = NA, correct = FALSE, decompose = FALSE)

\method{print}{breslow_day_test}(x, digits = 4, ...)
}
\arguments{
\item{x}{An object of class \code{"breslow_day_test"}}

\item{OR}{The common odds ratio to test against. If \code{NA} (the default), the
Mantel-Haenszel estimate is used.}

\item{correct}{Logical. If \code{TRUE}, the Tarone (1985) correction is applied.
Defaults to \code{FALSE}.}

\item{decompose}{Logical. If \code{TRUE} and \code{x} is 4-dimensional
(a \eqn{2 \times 2 \times R \times C}{2 x 2 x R x C} table), the test is
decomposed into row effects, column effects, and residual. Defaults to \code{FALSE}.
Ignored for non-4-dimensional tables.}

\item{digits}{Number of significant digits for the common OR. Default 4.}

\item{...}{Additional arguments (currently unused).}
}
\value{
A list of class \code{"breslow_day_test"} (also inheriting from \code{"htest"})
containing:
\item{statistic}{the chi-squared test statistic.}
\item{parameter}{degrees of freedom.}
\item{p.value}{\eqn{p}-value.}
\item{method}{character string describing the test.}
\item{data.name}{character string giving the name of the data.}
\item{or_vars}{names of the first two dimensions (the 2x2 table variables).}
\item{strata_vars}{names of the stratifying variables (dimensions 3 and beyond).}
\item{OR}{the common odds ratio used (MH estimate if \code{OR = NA} was supplied).}
\item{correct}{logical indicating whether Tarone correction was applied.}
\item{observed}{observed \eqn{a_j} counts (cell \eqn{[1,1]} of each stratum).}
\item{expected}{expected \eqn{\tilde{a}_j} counts under the common OR.}
\item{decomposed}{logical indicating if decomposition was performed.}

When \code{decompose = TRUE} (only for 4-dimensional tables), additional components:
\item{rows}{list with \code{statistic}, \code{df}, \code{p.value} for row effects.}
\item{cols}{list with \code{statistic}, \code{df}, \code{p.value} for column effects.}
\item{residual}{list with \code{statistic}, \code{df}, \code{p.value} for residual (interaction).}
}
\description{
Tests for homogeneity of odds ratios across strata in \eqn{2 \times 2 \times k}{2 x 2 x k}
tables (i.e., whether a common odds ratio fits all strata). Generalized to handle tables
of any dimensionality beyond 3. For 4-dimensional tables, optionally provides a two-way
decomposition of the homogeneity test into row effects, column effects, and residual,
analogous to \code{\link[=woolf_test]{woolf_test()}} with \code{decompose = TRUE}.
}
\details{
The Breslow-Day test (Breslow & Day, 1980) tests the hypothesis that a common odds ratio
\eqn{\psi} fits all \eqn{k} strata. Given a common OR (by default the Mantel-Haenszel
estimate), the expected cell count \eqn{\tilde{a}_j} in cell \eqn{[1,1]} of stratum
\eqn{j} is found by solving the quadratic:

\deqn{(\psi - 1)\tilde{a}_j^2 - [n_{2j} - m_{1j} + \psi(n_{1j} + m_{1j})]\tilde{a}_j
      + \psi \, m_{1j} n_{1j} = 0}

where \eqn{m_{1j}} and \eqn{m_{2j}} are the row margins and \eqn{n_{1j}} and
\eqn{n_{2j}} are the column margins of stratum \eqn{j}. The test statistic is:

\deqn{\chi^2_{BD} = \sum_{j=1}^{k} \frac{(a_j - \tilde{a}_j)^2}{\widehat{\text{Var}}(a_j)}}

where \eqn{\widehat{\text{Var}}(a_j) = (1/\tilde{a}_j + 1/\tilde{b}_j + 1/\tilde{c}_j +
1/\tilde{d}_j)^{-1}} and \eqn{\tilde{b}_j, \tilde{c}_j, \tilde{d}_j} are the remaining
expected cell counts. Under the null hypothesis, \eqn{\chi^2_{BD}} follows a chi-squared
distribution with \eqn{k - 1} degrees of freedom.

The Tarone (1985) correction subtracts a term to account for estimation of the common OR:

\deqn{\chi^2_{BD,T} = \chi^2_{BD} -
      \frac{(\sum_j a_j - \sum_j \tilde{a}_j)^2}{\sum_j \widehat{\text{Var}}(a_j)}}

\strong{Comparison with the Woolf test:}
The Woolf test uses log odds ratios and tests deviation from their weighted mean,
whereas the Breslow-Day test works on the cell-count scale against a specified common OR.
For large samples they agree closely; Breslow-Day is generally preferred when the
Mantel-Haenszel common OR is the quantity of interest.

\strong{Decomposition for 4-way tables:}
For a \eqn{2 \times 2 \times R \times C} table, when \code{decompose = TRUE}, the overall
test is decomposed as:

\deqn{\chi^2_{\text{Total}} = \chi^2_{\text{Rows}} + \chi^2_{\text{Cols}} +
      \chi^2_{\text{Residual}}}

where the row and column components use the row- and column-marginal (pooled) tables,
all tested against the same common OR as the overall test. The residual is defined by
subtraction and has \eqn{(R-1)(C-1)} degrees of freedom.
}
\examples{
# 3-way table
data(CoalMiners, package = "vcd")
breslow_day_test(CoalMiners)
breslow_day_test(CoalMiners, correct = TRUE)   # Tarone correction

# Compare with Woolf test
woolf_test(CoalMiners)

data(Heart, package = "vcdExtra")
breslow_day_test(Heart)

# 4-way table without decomposition
data(Fungicide, package = "vcdExtra")
breslow_day_test(Fungicide)

# 4-way table with decomposition
breslow_day_test(Fungicide, decompose = TRUE)

}
\references{
Breslow, N. E. & Day, N. E. (1980). \emph{Statistical Methods in Cancer Research.
Vol. 1: The Analysis of Case-Control Studies}. IARC Scientific Publications No. 32.
Lyon: International Agency for Research on Cancer.

Tarone, R. E. (1985). On heterogeneity tests based on efficient scores.
\emph{Biometrika}, \bold{72}, 91-95.

Lachin, J. M. (2000). \emph{Biostatistical Methods: The Assessment of Relative Risks}.
Wiley, p. 124-125.
}
\seealso{
\code{\link[stats:mantelhaen.test]{stats::mantelhaen.test()}}, \code{\link[=woolf_test]{woolf_test()}}, \code{\link[DescTools:BreslowDayTest]{DescTools::BreslowDayTest()}}

Other association tests:
\code{\link[=CMHtest]{CMHtest()}},
\code{\link[=GKgamma]{GKgamma()}},
\code{\link[=HLtest]{HLtest()}},
\code{\link[=woolf_test]{woolf_test()}},
\code{\link[=zero.test]{zero.test()}}
}
\author{
Andri Signorell, Michael Friendly (enhancements)
}
\concept{association tests}
