mosaicplot               package:base               R Documentation

Mosaic Plots

Description:

     Plots a mosaic on the current graphics device.

Usage:

     mosaicplot(x, main = NULL, xlab = NULL, ylab = NULL,
                        sort = NULL, off = NULL, dir = NULL,
                        color = FALSE, shade = FALSE, margin = NULL,
                        type = c("pearson", "deviance", "FT"), ...)
     mosaicplot(formula, data = NULL, ..., subset)

Arguments:

       x: a contingency table in array form, with optional category
          labels specified in the `dimnames(x)' attribute.  The table
          is best created by the `table()' command.

    main: character string for the mosaic title.

xlab,ylab: x- and y-axis labels used for the plot; by default, the
          first and second element of `names(dimnames(X))' (i.e., the
          name of the first and second variable in `X').

    sort: vector ordering of the variables, containing a permutation of
          the integers `1:length(dim(x))' (the default).

     off: vector of offsets to determine percentage spacing at each
          level of the mosaic (appropriate values are between 0 and 20,
          and the default is 10 at each level).  There should be one
          offset for each dimension of the contingency table.

     dir: vector of split directions (`"v"' for vertical and `"h"' for
          horizontal) for each level of the mosaic, one direction for
          each dimension of the contingency table.  The default
          consists of alternating directions, beginning with a vertical
          split.

   color: (`TRUE' or vector of integer colors) for color shading or
          (`FALSE', the default) for empty boxes with no shading. 
          Ignored if `shade' is not `FALSE'.

   shade: a logical indicating whether to produce extended mosaic
          plots, or a numeric vector of at most 5 distinct positive
          numbers giving the absolute values of the cut points for the
          residuals.  By default, `shade' is `FALSE', and simple
          mosaics are created.  Using `shade = TRUE' cuts absolute
          values at 2 and 4.

  margin: a list of vectors with the marginal totals to be fit in the
          log-linear model.  By default, an independence model is
          fitted. See `loglin' for further information.

    type: a character string indicating the type of residual to be
          represented.  Must be one of `"pearson"' (giving components
          of Pearson's chi-squared), `"deviance"' (giving components of
          the likelihood ratio chi-squared), or `"FT"' for the
          Freeman-Tukey residuals.  The value of this argument can be
          abbreviated.

 formula: a formula, such as `y ~ x'.

    data: a data.frame (or list), or a contingency table from which the
          variables in `formula' should be taken.

     ...: further arguments to be passed to or from methods.

  subset: an optional vector specifying a subset of observations to be
          used for plotting.

Details:

     This is a generic function.  It currently has a default method
     (`mosaicplot.default') and a formula interface
     (`mosaicplot.formula').

     Extended mosaic displays show the standardized residuals of a
     loglinear model of the counts from by the color and outline of the
     mosaic's tiles.  (Standardized residuals are often referred to a
     standard normal distribution.)  Negative residuals are drawn in
     shaded of red and with broken outlines; positive ones are drawn in
     blue with solid outlines.

     For the formula method, if `data' is an object inheriting from
     classes `"table"' or `"ftable"', or an array with more than 2
     dimensions, it is taken as a contingency table, and hence all
     entries should be nonnegative.  In this case, the left-hand side
     of `formula' should be empty, and the variables on the right-hand
     side should be taken from the names of the dimnames attribute of
     the contingency table.  A marginal table of these variables is
     computed, and a mosaic of this table is produced.

     Otherwise, `data' should be a data frame or matrix, list or
     environment containing the variables to be cross-tabulated.  In
     this case, after possibly selecting a subset of the data as
     specified by the `subset' argument, a contingency table is
     computed from the variables given in `formula', and a mosaic is
     produced from this.

     See Emerson (1998) for more information and a case study with
     television viewer data from Nielsen Media Research.

Author(s):

     S-PLUS original by John Emerson emerson@stat.yale.edu. Modified
     and enhanced for R by KH.

References:

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

     Emerson, J. W. (1998) Mosaic displays in S-PLUS: a general
     implementation and a case study. Statistical Computing and
     Graphics Newsletter (ASA), 9, 1, 17-23.

     Friendly, M. (1994) Mosaic displays for multi-way contingency
     tables. Journal of the American Statistical Association, 89,
     190-200.

     The home page of Michael Friendly (<URL:
     http://hotspur.psych.yorku.ca/SCS/friendly.html>) provides
     information on various aspects of graphical methods for analyzing
     categorical data, including mosaic plots.

See Also:

     `assocplot', `loglin'.

Examples:

     data(Titanic)
     mosaicplot(Titanic, main = "Survival on the Titanic", color = TRUE)
     ## Formula interface for tabulated data:
     mosaicplot(~ Sex + Age + Survived, data = Titanic, color = TRUE)

     data(HairEyeColor)
     mosaicplot(HairEyeColor, shade = TRUE)
     ## Independence model of hair and eye color and sex.  Indicates that
     ## there are significantly more blue eyed blond females than expected
     ## in the case of independence (and too few brown eyed blond females).
     mosaicplot(HairEyeColor, shade = TRUE, margin = list(c(1,2), 3))
     ## Model of joint independence of sex from hair and eye color.  Males
     ## are underrepresented among people with brown hair and eyes, and are
     ## overrepresented among people with brown hair and blue eyes, but not
     ## ``significantly''.

     ## Formula interface for raw data: visualize crosstabulation of numbers
     ## of gears and carburettors in Motor Trend car data.
     data(mtcars)
     mosaicplot(~ gear + carb, data = mtcars, color = TRUE)

