\HeaderA{spineplot}{Spine Plots and Spinograms}{spineplot}
\methaliasA{spineplot.default}{spineplot}{spineplot.default}
\methaliasA{spineplot.formula}{spineplot}{spineplot.formula}
\keyword{hplot}{spineplot}
\begin{Description}\relax
Spine plots are a special cases of mosaic plots, and can be seen as
a generalization of stacked (or highlighted) bar plots. Analogously,
spinograms are an extension of histograms.
\end{Description}
\begin{Usage}
\begin{verbatim}
spineplot(x, ...)

## Default S3 method:
spineplot(x, y = NULL,
          breaks = NULL, tol.ylab = 0.05, off = NULL,
          ylevels = NULL, col = NULL,
          main = "", xlab = NULL, ylab = NULL,
          xaxlabels = NULL, yaxlabels = NULL,
          xlim = NULL, ylim = c(0, 1), ...)

## S3 method for class 'formula':
spineplot(formula, data = list(),
          breaks = NULL, tol.ylab = 0.05, off = NULL,
          ylevels = NULL, col = NULL,
          main = "", xlab = NULL, ylab = NULL,
          xaxlabels = NULL, yaxlabels = NULL,
          xlim = NULL, ylim = c(0, 1), ...,
          subset = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an object, the default method expects either a single variable
(interpreted to be the explanatory variable) or a 2-way table.  See
details.
\item[\code{y}] a \code{"factor"} interpreted to be the dependent variable
\item[\code{formula}] a \code{"formula"} of type \code{y \textasciitilde{} x} with a single
dependent \code{"factor"} and a single explanatory variable.
\item[\code{data}] an optional data frame.
\item[\code{breaks}] if the explanatory variable is numeric, this controls how
it is discretized. \code{breaks} is passed to \code{\LinkA{hist}{hist}} and can
be a list of arguments.
\item[\code{tol.ylab}] convenience tolerance parameter for y-axis annotation.
If the distance between two labels drops under this threshold, they are
plotted equidistantly.
\item[\code{off}] vertical offset between the bars (in per cent). It is fixed to
\code{0} for spinograms and defaults to \code{2} for spine plots.
\item[\code{ylevels}] a character or numeric vector specifying in which order
the levels of the dependent variable should be plotted.
\item[\code{col}] a vector of fill colors of the same length as \code{levels(y)}.
The default is to call \code{\LinkA{gray.colors}{gray.colors}}.
\item[\code{main, xlab, ylab}] character strings for annotation
\item[\code{xaxlabels, yaxlabels}] character vectors for annotation of x and y axis.
Default to \code{levels(y)} and \code{levels(x)}, respectively for the
spine plot. For \code{xaxlabels} in the spinogram, the breaks are
used.
\item[\code{xlim, ylim}] the range of x and y values with sensible defaults.
\item[\code{...}] additional arguments passed to \code{\LinkA{rect}{rect}}.
\item[\code{subset}] an optional vector specifying a subset of observations
to be used for plotting.  
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{spineplot} creates either a spinogram or a spine plot.  It can
be called via \code{spineplot(x, y)} or \code{spineplot(y \textasciitilde{} x)} where
\code{y} is interpreted to be the dependent variable (and has to be
categorical) and \code{x} the explanatory variable.  \code{x} can be
either categorical (then a spine plot is created) or numerical (then a
spinogram is plotted).  Additionally, \code{spineplot} can also be
called with only a single argument which then has to be a 2-way table,
interpreted to correspond to \code{table(x, y)}.

Both, spine plots and spinograms, are essentially mosaic plots with
special formatting of spacing and shading.  Conceptually, they plot
\eqn{P(y | x)}{} against \eqn{P(x)}{}.  For the spine plot (where both
\eqn{x}{} and \eqn{y}{} are categorical), both quantities are approximated
by the corresponding empirical relative frequencies.  For the
spinogram (where \eqn{x}{} is numerical), \eqn{x}{} is first discretized
(by calling \code{\LinkA{hist}{hist}} with \code{breaks} argument) and then
empirical relative frequencies are taken.

Thus, spine plots can also be seen as a generalization of stacked bar
plots where not the heights but the widths of the bars corresponds to
the relative frequencies of \code{x}. The heights of the bars then
correspond to the conditional relative frequencies of \code{y} in
every \code{x} group. Analogously, spinograms extend stacked
histograms.
\end{Details}
\begin{Value}
The table visualized is returned invisibly.
\end{Value}
\begin{Author}\relax
Achim Zeileis \email{Achim.Zeileis@R-project.org}
\end{Author}
\begin{References}\relax
Friendly, M. (1994), Mosaic displays for multi-way contingency tables.
\emph{Journal of the American Statistical Association}, \bold{89},
190--200.

Hartigan, J.A., and Kleiner, B. (1984), A mosaic of television ratings.
\emph{The American Statistician}, \bold{38}, 32--35.

Hofmann, H., Theus, M. (2005), \emph{Interactive graphics for visualizing
conditional distributions}, Unpublished Manuscript.

Hummel, J. (1996), Linked bar charts: Analysing categorical data graphically.
\emph{Computational Statistics}, \bold{11}, 23--33.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{mosaicplot}{mosaicplot}}, \code{\LinkA{hist}{hist}}, \code{\LinkA{cdplot}{cdplot}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## treatment and improvement of patients with rheumatoid arthritis
treatment <- factor(rep(c(1, 2), c(43, 41)), levels = c(1, 2),
                    labels = c("placebo", "treated"))
improved <- factor(rep(c(1, 2, 3, 1, 2, 3), c(29, 7, 7, 13, 7, 21)),
                   levels = c(1, 2, 3),
                   labels = c("none", "some", "marked"))

## (dependence on a categorical variable)
(spineplot(improved ~ treatment))

## applications and admissions by department at UC Berkeley
## (two-way tables)
(spineplot(margin.table(UCBAdmissions, c(3, 2)),
           main = "Applications at UCB"))
(spineplot(margin.table(UCBAdmissions, c(3, 1)),
           main = "Admissions at UCB"))

## NASA space shuttle o-ring failures
fail <- factor(c(2, 2, 2, 2, 1, 1, 1, 1, 1, 1, 2, 1, 2, 1,
                 1, 1, 1, 2, 1, 1, 1, 1, 1),
               levels = c(1, 2), labels = c("no", "yes"))
temperature <- c(53, 57, 58, 63, 66, 67, 67, 67, 68, 69, 70, 70,
                 70, 70, 72, 73, 75, 75, 76, 76, 78, 79, 81)

## (dependence on a numerical variable)
(spineplot(fail ~ temperature))
(spineplot(fail ~ temperature, breaks = 3))
(spineplot(fail ~ temperature, breaks = quantile(temperature)))

## highlighting for failures
spineplot(fail ~ temperature, ylevels = 2:1)
\end{ExampleCode}
\end{Examples}

