vcd (version 0.9-0)

strucplot: Structured Displays of Contingency Tables

Description

This modular function visualizes certain aspects of high-dimensional contingency tables in a hierarchical way.

Usage

strucplot(x, residuals = NULL, expected = NULL,
  condvars = NULL, shade = NULL, type = c("observed", "expected"),
  residuals_type = c("Pearson", "deviance", "FT"), split_vertical = TRUE, 
  spacing = spacing_equal, spacing_args = list(),
  gp = NULL, gp_args = list(),
  labeling = labeling_text, labeling_args = list(),
  panel = struc_mosaic, panel_args = list(),
  legend = NULL, legend_args = list(),
  main = NULL, sub = NULL, margins = rep.int(2.5, 4),
  legend_width = unit(0.15, "npc"), title_gp = gpar(fontsize = 20),
  newpage = TRUE, pop = TRUE, keep_aspect_ratio = TRUE)

Arguments

x
a contingency table in array form, with optional category labels specified in the dimnames attribute.
residuals
optionally, an array of residuals of the same dimension as x (see details).
expected
optionally, an array of expected values of the same dimension as x, or alternatively the corresponding independence model specification as used by loglin or
condvars
number of conditioning variables, if any; those are expected to be ordered first in the table. This information is used for computing the expected values, and is also passed to the spacing functions (see
shade
logical specifying whether gp should be used or not (see gp). If TRUE and expected is unspecified, a default model is fitted: if condvars is specified, a corresponding conditional independenc
residuals_type
a character string indicating the type of residuals to be computed when none are supplied. Must be one of "pearson" (giving components of Pearson's chi-squared), "deviance" (giving components of the likelihood rat
type
a character string indicating whether the observed or the expected values of the table should be visualized.
split_vertical
vector of logicals of length $k$, where $k$ is the number of margins of x (values are recycled as needed). A TRUE component indicates that the tile(s) of the corresponding dimension should be split vertically, F
spacing
spacing object, spacing function, or a corresponding generating function (see details and spacings).
spacing_args
list of arguments for the spacing-generating function, if specified.
gp
object of class "gpar", shading function or a corresponding generating function (see details and shadings). Ignored if shade = FALSE.
gp_args
list of arguments for the shading-generating function, if specified.
labeling
either a labeling function, or a corresponding generating function (see details and labelings.
labeling_args
list of arguments for the labeling-generating function, if specified.
panel
either a panel function, or a corresponding generating function (see details). Currently, generating functions for mosaic plots (struc_mosaic) and association plots (
panel_args
list of arguments for the panel-generating function, if specified.
legend
either a legend-generating function, or a legend function (see details and legends), or a logical. If legend is NULL or TRUE and gp is a funct
legend_args
list of arguments for the legend-generating function, if specified.
main
either a logical, or a character string used for plotting the main title. If main is a logical and TRUE, the name of the object supplied as x is used.
sub
a character string used for plotting the subtitle.
margins
either an object of class "unit" of length 4, or a numeric vector of length 4. The elements are recycled as needed. The four components specify the top, right, bottom, and left m
legend_width
either an object of class "unit" of length 1, or a numeric value interpreted as proportion of the available horizontal space, specifying the width of the legend (if any).
pop
logical indicating whether the generated viewport tree should be removed at the end of the drawing or not.
title_gp
object of class "gpar" containing the graphical parameters used for the main and sub titles.
newpage
logical indicating whether a new page should be created for the plot or not.
keep_aspect_ratio
logical indicating whether the aspect ratio should be fixed or not.

Value

  • Invisibly, an object of class "structable" corresponding to the plot.

Details

This function---usually called by higher-level functions such as assoc and mosaic---generates conditioning plots of contingency tables. First, it sets up a set of viewports for main- and subtitles, legend, and the actual plot region. Then, residuals are computed as needed from observed and expected frequencies, where the expected frequencies are optionally computed for a specified independence model. Finally, the specified functions for spacing, gp, main plot, legend, and labeling are called to produce the plot. The function invisibly returns the "structable" object visualized.

Most elements of the plot, such as the panel function, the spacing between the tiles, the shading of the tiles, the labeling, and the legend, are modularized in functions and specified as parameters. For each element foo (= spacing, labeling, panel, or legend), strucplot takes two arguments: foo and foo_args, which can be used to specify the parameters in the following alternative ways:

  1. Passing a suitable function tofoowhich subsequently will be called fromstrucplotto compute shadings, labelings, etc.
  2. Passing a correspondinggeneratingfunction tofoo, along with parameters passed tofoo_args, that generates such a function. Generating functions must inherit from class"panel_generator".
  3. Except for the shading functions (shading_bar), passingfoo(foo_args)to thefooargument.
  4. For shadings and spacings, passing the final parameter object itself; see the corresponding help pages for more details on the data structures.
If legends are drawn, a cinemascope-like layout is used for the plot to preserve the 1:1 aspect ratio.

If type = "expected", the expected values are passed to the observed argument of the panel function, and the observed values to the expected argument.

Although the gp argument is typically used for shading, it can be used for arbitrary modifications of the tiles' graphics parameters (e.g., for highlighting particular cells, etc.).

See Also

assoc, mosaic, struc_assoc, struc_mosaic, structable, doubledecker, labelings, shadings, legends, spacings

Examples

Run this code
strucplot(Titanic)
strucplot(Titanic, panel = struc_assoc)
strucplot(Titanic, spacing = spacing_increase,
                   spacing_args = list(start = 0.5, rate = 1.5))
strucplot(Titanic, spacing = spacing_increase(start = 0.5, rate = 1.5))

## modify a tile's color
strucplot(Titanic, pop = FALSE)
grid.edit("rect..Class.1st..Sex.Male..Age.Adult..Survived.Yes",
          gp = gpar(fill = "red"))

Run the code above in your browser using DataCamp Workspace