src/library/stats/man/mantelhaen.test.Rd - R - Git at Google

 % File src/library/stats/man/mantelhaen.test.Rd
 % Part of the R package, https://www.R-project.org
 % Copyright 1995-2008 R Core Team
 % Distributed under GPL 2 or later

 \name{mantelhaen.test}
 \alias{mantelhaen.test}
 \title{Cochran-Mantel-Haenszel Chi-Squared Test for Count Data}
 \description{
   Performs a Cochran-Mantel-Haenszel chi-squared test of the null that
   two nominal variables are conditionally independent in each stratum,
   assuming that there is no three-way interaction.
 }
 \usage{
 mantelhaen.test(x, y = NULL, z = NULL,
                 alternative = c("two.sided", "less", "greater"),
                 correct = TRUE, exact = FALSE, conf.level = 0.95)
 }
 \arguments{
   \item{x}{either a 3-dimensional contingency table in array form where
     each dimension is at least 2 and the last dimension corresponds to
     the strata, or a factor object with at least 2 levels.}
   \item{y}{a factor object with at least 2 levels; ignored if \code{x}
     is an array.}
   \item{z}{a factor object with at least 2 levels identifying to which
     stratum the corresponding elements in \code{x} and \code{y} belong;
     ignored if \code{x} is an array.}
   \item{alternative}{indicates the alternative hypothesis and must be
     one of \code{"two.sided"}, \code{"greater"} or \code{"less"}.
     You can specify just the initial letter.
     Only used in the 2 by 2 by \eqn{K} case.}
   \item{correct}{a logical indicating whether to apply continuity
     correction when computing the test statistic.
     Only used in the 2 by 2 by \eqn{K} case.}
   \item{exact}{a logical indicating whether the Mantel-Haenszel test or
     the exact conditional test (given the strata margins) should be
     computed.
     Only used in the 2 by 2 by \eqn{K} case.}
   \item{conf.level}{confidence level for the returned confidence
     interval.
     Only used in the 2 by 2 by \eqn{K} case.}
 }
 \value{
   A list with class \code{"htest"} containing the following components:
   \item{statistic}{Only present if no exact test is performed.  In the
     classical case of a 2 by 2 by \eqn{K} table (i.e., of dichotomous
     underlying variables), the Mantel-Haenszel chi-squared statistic;
     otherwise, the generalized Cochran-Mantel-Haenszel statistic.}
   \item{parameter}{the degrees of freedom of the approximate chi-squared
     distribution of the test statistic (\eqn{1} in the classical case).
     Only present if no exact test is performed.}
   \item{p.value}{the p-value of the test.}
   \item{conf.int}{a confidence interval for the common odds ratio.
     Only present in the 2 by 2 by \eqn{K} case.}
   \item{estimate}{an estimate of the common odds ratio.  If an exact
     test is performed, the conditional Maximum Likelihood Estimate is
     given; otherwise, the Mantel-Haenszel estimate.
     Only present in the 2 by 2 by \eqn{K} case.}
   \item{null.value}{the common odds ratio under the null of
     independence, \code{1}.
     Only present in the 2 by 2 by \eqn{K} case.}
   \item{alternative}{a character string describing the alternative
     hypothesis.
     Only present in the 2 by 2 by \eqn{K} case.}
   \item{method}{a character string indicating the method employed, and whether
     or not continuity correction was used.}
   \item{data.name}{a character string giving the names of the data.}
 }
 \details{
   If \code{x} is an array, each dimension must be at least 2, and
   the entries should be nonnegative integers.  \code{NA}'s are not
   allowed.  Otherwise, \code{x}, \code{y} and \code{z} must have the
   same length.  Triples containing \code{NA}'s are removed.  All
   variables must take at least two different values.
 }
 \note{
   The asymptotic distribution is only valid if there is no three-way
   interaction.  In the classical 2 by 2 by \eqn{K} case, this is
   equivalent to the conditional odds ratios in each stratum being
   identical.  Currently, no inference on homogeneity of the odds ratios
   is performed.

   See also the example below.
 }
 \references{
   Alan Agresti (1990).
   \emph{Categorical data analysis}.
   New York: Wiley.
   Pages 230--235.

   Alan Agresti (2002).
   \emph{Categorical data analysis} (second edition).
   New York: Wiley.
 }
 \examples{
 ## Agresti (1990), pages 231--237, Penicillin and Rabbits
 ## Investigation of the effectiveness of immediately injected or 1.5
 ##  hours delayed penicillin in protecting rabbits against a lethal
 ##  injection with beta-hemolytic streptococci.
 Rabbits <-
 array(c(0, 0, 6, 5,
         3, 0, 3, 6,
         6, 2, 0, 4,
         5, 6, 1, 0,
         2, 5, 0, 0),
       dim = c(2, 2, 5),
       dimnames = list(
           Delay = c("None", "1.5h"),
           Response = c("Cured", "Died"),
           Penicillin.Level = c("1/8", "1/4", "1/2", "1", "4")))
 Rabbits
 ## Classical Mantel-Haenszel test
 mantelhaen.test(Rabbits)
 ## => p = 0.047, some evidence for higher cure rate of immediate
 ##               injection
 ## Exact conditional test
 mantelhaen.test(Rabbits, exact = TRUE)
 ## => p - 0.040
 ## Exact conditional test for one-sided alternative of a higher
 ## cure rate for immediate injection
 mantelhaen.test(Rabbits, exact = TRUE, alternative = "greater")
 ## => p = 0.020

 ## UC Berkeley Student Admissions
 mantelhaen.test(UCBAdmissions)
 ## No evidence for association between admission and gender
 ## when adjusted for department.  However,
 apply(UCBAdmissions, 3, function(x) (x[1,1]*x[2,2])/(x[1,2]*x[2,1]))
 ## This suggests that the assumption of homogeneous (conditional)
 ## odds ratios may be violated.  The traditional approach would be
 ## using the Woolf test for interaction:
 woolf <- function(x) {
   x <- x + 1 / 2
   k <- dim(x)[3]
   or <- apply(x, 3, function(x) (x[1,1]*x[2,2])/(x[1,2]*x[2,1]))
   w <-  apply(x, 3, function(x) 1 / sum(1 / x))
   1 - pchisq(sum(w * (log(or) - weighted.mean(log(or), w)) ^ 2), k - 1)
 }
 woolf(UCBAdmissions)
 ## => p = 0.003, indicating that there is significant heterogeneity.
 ## (And hence the Mantel-Haenszel test cannot be used.)

 ## Agresti (2002), p. 287f and p. 297.
 ## Job Satisfaction example.
 Satisfaction <-
     as.table(array(c(1, 2, 0, 0, 3, 3, 1, 2,
                      11, 17, 8, 4, 2, 3, 5, 2,
                      1, 0, 0, 0, 1, 3, 0, 1,
                      2, 5, 7, 9, 1, 1, 3, 6),
                    dim = c(4, 4, 2),
                    dimnames =
                    list(Income =
                         c("<5000", "5000-15000",
                           "15000-25000", ">25000"),
                         "Job Satisfaction" =
                         c("V_D", "L_S", "M_S", "V_S"),
                         Gender = c("Female", "Male"))))
 ## (Satisfaction categories abbreviated for convenience.)
 ftable(. ~ Gender + Income, Satisfaction)
 ## Table 7.8 in Agresti (2002), p. 288.
 mantelhaen.test(Satisfaction)
 ## See Table 7.12 in Agresti (2002), p. 297.
 }
 \keyword{htest}
	% File src/library/stats/man/mantelhaen.test.Rd
	% Part of the R package, https://www.R-project.org
	% Copyright 1995-2008 R Core Team
	% Distributed under GPL 2 or later

	\name{mantelhaen.test}
	\alias{mantelhaen.test}
	\title{Cochran-Mantel-Haenszel Chi-Squared Test for Count Data}
	\description{
	Performs a Cochran-Mantel-Haenszel chi-squared test of the null that
	two nominal variables are conditionally independent in each stratum,
	assuming that there is no three-way interaction.
	}
	\usage{
	mantelhaen.test(x, y = NULL, z = NULL,
	alternative = c("two.sided", "less", "greater"),
	correct = TRUE, exact = FALSE, conf.level = 0.95)
	}
	\arguments{
	\item{x}{either a 3-dimensional contingency table in array form where
	each dimension is at least 2 and the last dimension corresponds to
	the strata, or a factor object with at least 2 levels.}
	\item{y}{a factor object with at least 2 levels; ignored if \code{x}
	is an array.}
	\item{z}{a factor object with at least 2 levels identifying to which
	stratum the corresponding elements in \code{x} and \code{y} belong;
	ignored if \code{x} is an array.}
	\item{alternative}{indicates the alternative hypothesis and must be
	one of \code{"two.sided"}, \code{"greater"} or \code{"less"}.
	You can specify just the initial letter.
	Only used in the 2 by 2 by \eqn{K} case.}
	\item{correct}{a logical indicating whether to apply continuity
	correction when computing the test statistic.
	Only used in the 2 by 2 by \eqn{K} case.}
	\item{exact}{a logical indicating whether the Mantel-Haenszel test or
	the exact conditional test (given the strata margins) should be
	computed.
	Only used in the 2 by 2 by \eqn{K} case.}
	\item{conf.level}{confidence level for the returned confidence
	interval.
	Only used in the 2 by 2 by \eqn{K} case.}
	}
	\value{
	A list with class \code{"htest"} containing the following components:
	\item{statistic}{Only present if no exact test is performed. In the
	classical case of a 2 by 2 by \eqn{K} table (i.e., of dichotomous
	underlying variables), the Mantel-Haenszel chi-squared statistic;
	otherwise, the generalized Cochran-Mantel-Haenszel statistic.}
	\item{parameter}{the degrees of freedom of the approximate chi-squared
	distribution of the test statistic (\eqn{1} in the classical case).
	Only present if no exact test is performed.}
	\item{p.value}{the p-value of the test.}
	\item{conf.int}{a confidence interval for the common odds ratio.
	Only present in the 2 by 2 by \eqn{K} case.}
	\item{estimate}{an estimate of the common odds ratio. If an exact
	test is performed, the conditional Maximum Likelihood Estimate is
	given; otherwise, the Mantel-Haenszel estimate.
	Only present in the 2 by 2 by \eqn{K} case.}
	\item{null.value}{the common odds ratio under the null of
	independence, \code{1}.
	Only present in the 2 by 2 by \eqn{K} case.}
	\item{alternative}{a character string describing the alternative
	hypothesis.
	Only present in the 2 by 2 by \eqn{K} case.}
	\item{method}{a character string indicating the method employed, and whether
	or not continuity correction was used.}
	\item{data.name}{a character string giving the names of the data.}
	}
	\details{
	If \code{x} is an array, each dimension must be at least 2, and
	the entries should be nonnegative integers. \code{NA}'s are not
	allowed. Otherwise, \code{x}, \code{y} and \code{z} must have the
	same length. Triples containing \code{NA}'s are removed. All
	variables must take at least two different values.
	}
	\note{
	The asymptotic distribution is only valid if there is no three-way
	interaction. In the classical 2 by 2 by \eqn{K} case, this is
	equivalent to the conditional odds ratios in each stratum being
	identical. Currently, no inference on homogeneity of the odds ratios
	is performed.

	See also the example below.
	}
	\references{
	Alan Agresti (1990).
	\emph{Categorical data analysis}.
	New York: Wiley.
	Pages 230--235.

	Alan Agresti (2002).
	\emph{Categorical data analysis} (second edition).
	New York: Wiley.
	}
	\examples{
	## Agresti (1990), pages 231--237, Penicillin and Rabbits
	## Investigation of the effectiveness of immediately injected or 1.5
	## hours delayed penicillin in protecting rabbits against a lethal
	## injection with beta-hemolytic streptococci.
	Rabbits <-
	array(c(0, 0, 6, 5,
	3, 0, 3, 6,
	6, 2, 0, 4,
	5, 6, 1, 0,
	2, 5, 0, 0),
	dim = c(2, 2, 5),
	dimnames = list(
	Delay = c("None", "1.5h"),
	Response = c("Cured", "Died"),
	Penicillin.Level = c("1/8", "1/4", "1/2", "1", "4")))
	Rabbits
	## Classical Mantel-Haenszel test
	mantelhaen.test(Rabbits)
	## => p = 0.047, some evidence for higher cure rate of immediate
	## injection
	## Exact conditional test
	mantelhaen.test(Rabbits, exact = TRUE)
	## => p - 0.040
	## Exact conditional test for one-sided alternative of a higher
	## cure rate for immediate injection
	mantelhaen.test(Rabbits, exact = TRUE, alternative = "greater")
	## => p = 0.020

	## UC Berkeley Student Admissions
	mantelhaen.test(UCBAdmissions)
	## No evidence for association between admission and gender
	## when adjusted for department. However,
	apply(UCBAdmissions, 3, function(x) (x[1,1]x[2,2])/(x[1,2]x[2,1]))
	## This suggests that the assumption of homogeneous (conditional)
	## odds ratios may be violated. The traditional approach would be
	## using the Woolf test for interaction:
	woolf <- function(x) {
	x <- x + 1 / 2
	k <- dim(x)[3]
	or <- apply(x, 3, function(x) (x[1,1]x[2,2])/(x[1,2]x[2,1]))
	w <- apply(x, 3, function(x) 1 / sum(1 / x))
	1 - pchisq(sum(w * (log(or) - weighted.mean(log(or), w)) ^ 2), k - 1)
	}
	woolf(UCBAdmissions)
	## => p = 0.003, indicating that there is significant heterogeneity.
	## (And hence the Mantel-Haenszel test cannot be used.)

	## Agresti (2002), p. 287f and p. 297.
	## Job Satisfaction example.
	Satisfaction <-
	as.table(array(c(1, 2, 0, 0, 3, 3, 1, 2,
	11, 17, 8, 4, 2, 3, 5, 2,
	1, 0, 0, 0, 1, 3, 0, 1,
	2, 5, 7, 9, 1, 1, 3, 6),
	dim = c(4, 4, 2),
	dimnames =
	list(Income =
	c("<5000", "5000-15000",
	"15000-25000", ">25000"),
	"Job Satisfaction" =
	c("V_D", "L_S", "M_S", "V_S"),
	Gender = c("Female", "Male"))))
	## (Satisfaction categories abbreviated for convenience.)
	ftable(. ~ Gender + Income, Satisfaction)
	## Table 7.8 in Agresti (2002), p. 288.
	mantelhaen.test(Satisfaction)
	## See Table 7.12 in Agresti (2002), p. 297.
	}
	\keyword{htest}