| % File src/library/graphics/man/spineplot.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{spineplot} |
| \alias{spineplot} |
| \alias{spineplot.default} |
| \alias{spineplot.formula} |
| \title{Spine Plots and Spinograms} |
| \description{ |
| 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. |
| } |
| \usage{ |
| spineplot(x, \dots) |
| |
| \method{spineplot}{default}(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), axes = TRUE, \dots) |
| |
| \method{spineplot}{formula}(formula, data = 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), axes = TRUE, \dots, |
| subset = NULL, drop.unused.levels = FALSE) |
| } |
| \arguments{ |
| \item{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{y}{a \code{"factor"} interpreted to be the dependent variable} |
| \item{formula}{a \code{"formula"} of type \code{y ~ x} with a single |
| dependent \code{"factor"} and a single explanatory variable.} |
| \item{data}{an optional data frame.} |
| \item{breaks}{if the explanatory variable is numeric, this controls how |
| it is discretized. \code{breaks} is passed to \code{\link{hist}} and can |
| be a list of arguments.} |
| \item{tol.ylab}{convenience tolerance parameter for y-axis annotation. |
| If the distance between two labels drops under this threshold, they are |
| plotted equidistantly.} |
| \item{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{ylevels}{a character or numeric vector specifying in which order |
| the levels of the dependent variable should be plotted.} |
| \item{col}{a vector of fill colors of the same length as \code{levels(y)}. |
| The default is to call \code{\link{gray.colors}}.} |
| \item{main, xlab, ylab}{character strings for annotation} |
| \item{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{xlim, ylim}{the range of x and y values with sensible defaults.} |
| \item{axes}{logical. If \code{FALSE} all axes (including those giving |
| level names) are suppressed.} |
| \item{\dots}{additional arguments passed to \code{\link{rect}}.} |
| \item{subset}{an optional vector specifying a subset of observations |
| to be used for plotting.} |
| \item{drop.unused.levels}{should factors have unused levels dropped? |
| Defaults to \code{FALSE}.} |
| } |
| \details{ |
| \code{spineplot} creates either a spinogram or a spine plot. It can |
| be called via \code{spineplot(x, y)} or \code{spineplot(y ~ 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{\link{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. |
| } |
| \value{ |
| The table visualized is returned invisibly. |
| } |
| \seealso{ |
| \code{\link{mosaicplot}}, \code{\link{hist}}, \code{\link{cdplot}} |
| } |
| \references{ |
| Friendly, M. (1994). |
| Mosaic displays for multi-way contingency tables. |
| \emph{Journal of the American Statistical Association}, \bold{89}, |
| 190--200. |
| \doi{10.2307/2291215}. |
| |
| Hartigan, J.A., and Kleiner, B. (1984). |
| A mosaic of television ratings. |
| \emph{The American Statistician}, \bold{38}, 32--35. |
| \doi{10.2307/2683556}. |
| |
| 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. |
| } |
| \author{ |
| Achim Zeileis \email{Achim.Zeileis@R-project.org} |
| } |
| \examples{ |
| ## 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) |
| } |
| \keyword{hplot} |