\inputencoding{latin1}
\HeaderA{assocplot}{Association Plots}{assocplot}
\keyword{hplot}{assocplot}
\begin{Description}\relax
Produce a Cohen-Friendly association plot indicating deviations from
independence of rows and columns in a 2-dimensional contingency
table.
\end{Description}
\begin{Usage}
\begin{verbatim}
assocplot(x, col = c("black", "red"), space = 0.3,
          main = NULL, xlab = NULL, ylab = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a two-dimensional contingency table in matrix form.
\item[\code{col}] a character vector of length two giving the colors used for
drawing positive and negative Pearson residuals, respectively.
\item[\code{space}] the amount of space (as a fraction of the average
rectangle width and height) left between each rectangle.
\item[\code{main}] overall title for the plot.
\item[\code{xlab}] a label for the x axis.  Defaults to the name (if any) of
the row dimension in \code{x}.
\item[\code{ylab}] a label for the y axis.  Defaults to the name (if any) of
the column dimension in \code{x}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
For a two-way contingency table, the signed contribution to Pearson's
\eqn{\chi^2}{chi^2} for cell \eqn{i, j}{} is \eqn{d_{ij} = (f_{ij} -
e_{ij}) / \sqrt{e_{ij}}}{d_{ij} = (f_{ij} - e_{ij}) / sqrt(e_{ij})},
where \eqn{f_{ij}}{} and \eqn{e_{ij}}{} are the observed and expected
counts corresponding to the cell.  In the Cohen-Friendly association
plot, each cell is represented by a rectangle that has (signed) height
proportional to \eqn{d_{ij}}{} and width proportional to
\eqn{\sqrt{e_{ij}}}{sqrt(e_{ij})}, so that the area of the box is
proportional to the difference in observed and expected frequencies.
The rectangles in each row are positioned relative to a baseline
indicating independence (\eqn{d_{ij} = 0}{}).  If the observed frequency
of a cell is greater than the expected one, the box rises above the
baseline and is shaded in the color specified by the first element of
\code{col}, which defaults to black; otherwise, the box falls below
the baseline and is shaded in the color specified by the second
element of \code{col}, which defaults to red.

A more flexible and extensible implementation of association plots
written in the grid graphics system is provided in the function
\code{\LinkA{assoc}{assoc}} in the contributed package \pkg{vcd} (Meyer,
Zeileis and Hornik, 2005).
\end{Details}
\begin{References}\relax
Cohen, A. (1980),
On the graphical display of the significant components in a two-way
contingency table.
\emph{Communications in Statistics---Theory and Methods}, \bold{A9},
1025--1041.

Friendly, M. (1992),
Graphical methods for categorical data.
\emph{SAS User Group International Conference Proceedings}, \bold{17},
190--200.
\url{http://www.math.yorku.ca/SCS/sugi/sugi17-paper.html}

Meyer, D., Zeileis, A., and Hornik, K. (2005)
The strucplot framework: Visualizing multi-way contingency tables with vcd.
\emph{Report 22}, Department of Statistics and Mathematics, 
Wirtschaftsuniversität Wien, Research Report Series.
\url{http://epub.wu-wien.ac.at/dyn/openURL?id=oai:epub.wu-wien.ac.at:epub-wu-01_8a1}
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{mosaicplot}{mosaicplot}}, \code{\LinkA{chisq.test}{chisq.test}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Aggregate over sex:
x <- margin.table(HairEyeColor, c(1, 2))
x
assocplot(x, main = "Relation between hair and eye color")
\end{ExampleCode}
\end{Examples}

