% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CMHtest.R
\name{CMHtest}
\alias{CMHtest}
\alias{CMHtest.formula}
\alias{CMHtest.default}
\alias{Cochran}
\alias{Mantel}
\alias{Haenszel}
\alias{test}
\alias{print.CMHtest}
\title{Generalized Cochran-Mantel-Haenszel Tests}
\usage{
CMHtest(x, ...)

\method{CMHtest}{formula}(formula, data = NULL, subset = NULL, na.action = NULL, ...)

\method{CMHtest}{default}(
  x,
  strata = NULL,
  rscores = 1:R,
  cscores = 1:C,
  types = c("cor", "rmeans", "cmeans", "general"),
  overall = FALSE,
  details = overall,
  ...
)

\method{print}{CMHtest}(
  x,
  digits = max(getOption("digits") - 2, 3),
  layout = c("table", "2x2"),
  stars = FALSE,
  scale = FALSE,
  ...
)
}
\arguments{
\item{x}{A 2+ way contingency table in array form, or a class \code{"table"}
object with optional category labels specified in the dimnames(x) attribute.}

\item{\dots}{Other arguments passed to default method.}

\item{formula}{a formula specifying the variables used to create a
contingency table from \code{data}.  This should be a one-sided formula when
\code{data} is in array form, and a two-sided formula with a response
\code{Freq} if \code{data} is a data frame with a cell frequency variable.
For convenience, conditioning formulas can be specified indicating strata.}

\item{data}{either a data frame, or an object of class \code{"table"} or \code{"ftable"}.}

\item{subset}{an optional vector specifying a subset of observations to be used.}

\item{na.action}{a function which indicates what should happen when the data contain \code{NA}s.
Ignored if \code{data} is a contingency table.}

\item{strata}{For a 3- or higher-way table, the names or numbers of the
factors to be treated as strata.  By default, the first 2 factors are
treated as the main table variables, and all others considered stratifying factors.}

\item{rscores}{Row scores.  Either a set of numbers (typically integers,
\code{1:R}) or the string \code{"midrank"} for standardized midrank scores,
or \code{NULL} to exclude tests that depend on row scores.}

\item{cscores}{Column scores. Same as for row scores.}

\item{types}{Types of CMH tests to compute: Any one or more of \code{c("cor", "cmeans", "rmeans", "general")}, or
\code{"ALL"} for all of these.}

\item{overall}{logical. Whether to calculate overall tests, controlling for the stratifying factors.}

\item{details}{logical.  Whether to include computational details in the result}

\item{digits}{Digits to print.}

\item{layout}{For \code{print.CMHtest()}, one of \code{"table"} (default) for the
traditional flat 4-row printout, or \code{"2x2"} to reorganize the four CMH
statistics into a 2x2 table crossing how the row and column variables are
each treated (general/nominal vs. ordered/scored). \code{layout = "2x2"}
requires all four of \code{cor}, \code{rmeans}, \code{cmeans}, \code{general} to be present in
\code{x}; if \code{types} or \code{rscores}/\code{cscores = NULL} excluded any of them, this
falls back to \code{layout = "table"} with a warning. See \strong{Details}.}

\item{stars}{For \code{print.CMHtest()} with \code{layout = "2x2"}, logical: annotate
each cell with significance stars (\code{'***'}/\code{'**'}/\code{'*'} for p < .001/.01/.05)
based on its own (Chisq, Df). Default \code{FALSE}, matching \code{layout = "table"}'s
plain display.}

\item{scale}{For \code{print.CMHtest()} with \code{layout = "2x2"}, logical: show
\code{Chisq/Df} instead of \code{Chisq (Df)} in each cell -- normalizes for the very
different degrees of freedom across cells. Default \code{FALSE}.}
}
\value{
An object of class \code{"CMHtest"} , a list with the following 4 components:

\item{table}{A matrix containing the test statistics, with columns \code{Chisq}, \code{Df} and \code{Prob} }
\item{names}{The names of the table row and column variables}
\item{rscore}{Row scores}
\item{cscore}{Column scores}

If \code{details==TRUE}, additional components are included.

If there are strata, the result is a list of \code{"CMHtest"} objects. If
\code{overall=TRUE} another component, labeled \code{ALL} is appended to the
list.
}
\description{
Provides generalized Cochran-Mantel-Haenszel tests of association of two
possibly ordered factors, optionally stratified other factor(s).  With
strata, \code{CMHtest} calculates these tests for each level of the
stratifying variables and also provides overall tests controlling for the
strata. See \strong{Details} for descriptions of what these entail and enhancements to this function.
}
\details{
For ordinal factors, more powerful tests than the test for general
association (independence) are obtained by assigning scores to the row and
column categories.

The standard \eqn{\chi^2} tests for association in a two-way table treat
both table factors as nominal (unordered) categories. When one or both
factors of a two-way table are quantitative or ordinal, more powerful tests
of association may be obtained by taking ordinality into account using row
and or column scores to test for linear trends or differences in row or
column means.

The CMH analysis for a two-way table produces \strong{generalized}
Cochran-Mantel-Haenszel statistics (Landis etal., 1978):
\itemize{
\item The CMH \strong{correlation} statistic (\code{"cor"}), treating both factors as
ordered. For a given statum, with equally spaced row and column scores,
this CMH statistic reduces to \eqn{(n-1) r^2}, where \eqn{r} is the
Pearson correlation between X and Y. With \code{"midrank"} scores, this CMH
statistic is analogous to \eqn{(n-1) r_S^2}, using the Spearman rank
correlation.
\item The \strong{ANOVA} (row mean scores and column mean scores) statistics,
treat the columns and rows respectively as ordinal, and are sensitive to
mean shifts over columns or rows. These are transforms of the \eqn{F}
statistics from one-way ANOVAs with equally spaced scores and to
Kruskal-Wallis tests with \code{"midrank"} scores.
\item The CMH \strong{general} association statistic treat both factors as
unordered, and give a test closely related to the Pearson \eqn{\chi^2}
test. When there is more than one stratum, the overall general CMH
statistic gives a stratum-adjusted Pearson \eqn{\chi^2}, equivalent to
what is calculated by \code{\link[stats]{mantelhaen.test}}.
}
\subsection{Strata}{

For a 3+ way table, one table of CMH tests is produced for each combination
of the factors identified as \code{strata}. If \code{overall=TRUE}, an
additional table is calculated for the same two primary variables,
controlling for (pooling over) the \code{strata} variables.

These overall tests implicitly assume no interactions between the primary
variables and the strata and they will have low power in the presence of
interactions.

Note that strata combinations with insufficient data (less than 2
observations) are automatically omitted from the analysis.
}

\subsection{2x2 layout}{

\code{print.CMHtest(layout = "2x2")} is an attempt to provide an alternative view of these
four statistics that may be more useful/understandable than the traditional flat 4-row
table: it reorganizes them into a 2x2 table crossing how the row and column variables
are each treated (general/nominal vs. ordered/scored).

The corner cell of this display (\code{general - rmeans - cmeans + cor}, a "diff of diffs")
is algebraically consistent but its distribution as chi-square(df) is
\strong{experimental/unverified} -- these are four different quadratic-form statistics, not
a nested sequence of LR tests, so the naive inclusion-exclusion combination is not
guaranteed to be non-negative in general (see \verb{dev/CMH-2x2.md} for a worked
counter-example and a loglinear \code{LRstats()}-based alternative).
}
}
\examples{

data(JobSat, package="vcdExtra")
CMHtest(JobSat)
CMHtest(JobSat, rscores="midrank", cscores="midrank")

# formula interface
CMHtest(~ ., data=JobSat)

# A 3-way table (both factors ordinal)
data(MSPatients, package="vcd")
CMHtest(MSPatients)


# also calculate overall tests, controlling for Patient
CMHtest(MSPatients, overall = TRUE)
# compare with mantelhaen.test
mantelhaen.test(MSPatients)

# formula interface
CMHtest(~ ., data = MSPatients, overall = TRUE)

# using a frequency data.frame
CMHtest(xtabs(Freq~ses + mental, data = Mental))
# or, more simply
CMHtest(Freq~ses + mental, data = Mental)

# conditioning formulae
CMHtest(Freq~right + left | gender, data = VisualAcuity)

CMHtest(Freq ~ attitude + memory | education + age, data = Punishment)

# 2x2 layout, reorganizing the four CMH statistics by how the row/column
# variables are treated (general/nominal vs. ordered/scored)
cmh_mental <- CMHtest(Freq ~ ses + mental, data = Mental)
print(cmh_mental, layout = "2x2")
print(cmh_mental, layout = "2x2", stars = TRUE)
print(cmh_mental, layout = "2x2", scale = TRUE)


# Stokes etal, Table 5.1, p 92: two unordered factors
parties <- matrix(
	c(221, 160, 360, 140,
	  200, 291, 160, 311,
	  208, 106, 316, 97),
	nrow=3, ncol=4,
	byrow=TRUE)
dimnames(parties) <- list(party=c("Dem", "Indep", "Rep"),
             neighborhood=c("Bayside", "Highland", "Longview", "Sheffield"))
CMHtest(parties, rscores=NULL, cscores=NULL)

# compare with Pearson chisquare
chisq.test(parties)

}
\references{
Stokes, M. E. & Davis, C. S.  & Koch, G., (2000).
\emph{Categorical Data Analysis using the SAS System}, 2nd Ed., Cary, NC:
SAS Institute, pp 74-75, 92-101, 124-129.  Details of the computation are
given at: \url{http://support.sas.com/documentation/cdl/en/statug/63033/HTML/default/viewer.htm#statug_freq_a0000000648.htm}

Cochran, W. G. (1954), Some Methods for Strengthening the Common
\eqn{\chi^2} Tests, \emph{Biometrics}, 10, 417-451.

Landis, R. J., Heyman, E. R., and Koch, G. G. (1978).  Average Partial
Association in Three-way Contingency Tables: A Review and Discussion of
Alternative Tests, \emph{International Statistical Review}, \strong{46},
237-254.

Mantel, N. (1963), Chi-square Tests with One Degree of Freedom: Extensions
of the Mantel-Haenszel Procedure," \emph{Journal of the American Statistical
Association}, 58, 690-700.
}
\seealso{
\code{\link[coin]{cmh_test}} provides the CMH test of general
association; \code{\link[coin]{lbl_test}} provides the CMH correlation test
of linear by linear association.

\code{\link[stats]{mantelhaen.test}} provides the overall general
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

Other association tests:
\code{\link[=GKgamma]{GKgamma()}},
\code{\link[=HLtest]{HLtest()}},
\code{\link[=breslow_day_test]{breslow_day_test()}},
\code{\link[=woolf_test]{woolf_test()}},
\code{\link[=zero.test]{zero.test()}}
}
\author{
Michael Friendly
}
\concept{association tests}
\keyword{htest}
