mosaicplot         package:graphics         R Documentation(latin1)

Mosaic Plots

Description:

     Plots a mosaic on the current graphics device.

Usage:

     mosaicplot(x, ...)

     ## Default S3 method:
     mosaicplot(x, main = deparse(substitute(x)), 
                sub = NULL, xlab = NULL, ylab = NULL,
                sort = NULL, off = NULL, dir = NULL,
                color = NULL, shade = FALSE, margin = NULL,
                cex.axis = 0.66, las = par("las"),
                type = c("pearson", "deviance", "FT"), ...)

     ## S3 method for class 'formula':
     mosaicplot(formula, data = NULL, ...,
                main = deparse(substitute(data)), subset,
                na.action = stats::na.omit)

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.

     sub: character string for the mosaic sub-title (at bottom).

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 20 times the number of splits for
          2-dimensional tables, and 10 otherwise.  Rescaled to
          maximally 50, and recycled if necessary.

     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: logical or (recycling) vector of colors for color shading,
          used only when 'shade' is 'FALSE', or 'NULL' (default).  By
          default, grey boxes are drawn.  'color=TRUE' uses a
          gamma-corrected grey palette.  'color=FALSE' gives empty
          boxes with no shading.

   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.

cex.axis: The magnification to be used for axis annotation, as a
          multiple of 'par("cex")'.

     las: numeric; the style of axis labels, see 'par'.

    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 in the
          data frame to be used for plotting.

na.action: a function which indicates what should happen when the data
          contains variables to be cross-tabulated, and these variables
          contain 'NA's.  The default is to omit cases which have an
          'NA' in any variable.  Since the tabulation will omit all
          cases containing missing values, this will only be useful if
          the 'na.action' function replaces missing values.

Details:

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

     Extended mosaic displays visualize standardized residuals of a
     loglinear model for the table by 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.

     Missing values are not supported except via an 'na.action'
     function when 'data' contains variables to be cross-tabulated.

     A more flexible and extensible implementation of mosaic plots
     written in the grid graphics system is provided in the function
     'mosaic' in the contributed package 'vcd' (Meyer, Zeileis and
     Hornik, 2005).

Author(s):

     S-PLUS original by John Emerson john.emerson@yale.edu. Originally
     modified and enhanced for R by Kurt Hornik.

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.

     Meyer, D., Zeileis, A., and Hornik, K. (2005) The strucplot
     framework: Visualizing multi-way contingency tables with vcd.
     _Report 22_, Department of Statistics and Mathematics, 
     Wirtschaftsuniversitaet Wien, Research Report Series. <URL:
     http://epub.wu-wien.ac.at/dyn/openURL?id=oai:epub.wu-wien.ac.at:epub-wu-01_8a1>

     The home page of Michael Friendly (<URL:
     http://www.math.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:

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

     mosaicplot(HairEyeColor, shade = TRUE)
     ## Independence model of hair and eye color and sex.  Indicates that
     ## there are more blue eyed blonde females than expected in the case 
     ## of independence and too few brown eyed blonde females.
     ## The corresponding model is:
     fm <- loglin(HairEyeColor, list(1, 2, 3))
     pchisq(fm$pearson, fm$df, lower.tail = FALSE)

     mosaicplot(HairEyeColor, shade = TRUE, margin = list(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.
     ## The corresponding model is:
     fm <- loglin(HairEyeColor, list(1:2, 3))
     pchisq(fm$pearson, fm$df, lower.tail = FALSE)

     ## Formula interface for raw data: visualize cross-tabulation of numbers
     ## of gears and carburettors in Motor Trend car data.
     mosaicplot(~ gear + carb, data = mtcars, color = TRUE, las = 1)
     # color recycling
     mosaicplot(~ gear + carb, data = mtcars, color = 2:3, las = 1)

