This modular function visualizes certain aspects of high-dimensional contingency tables in a hierarchical way.
strucplot(x, residuals = NULL, expected = NULL,
condvars = NULL, shade = NULL, type = c("observed", "expected"),
residuals_type = NULL, df = NULL, split_vertical = NULL,
spacing = spacing_equal, spacing_args = list(),
gp = NULL, gp_args = list(),
labeling = labeling_border, labeling_args = list(),
core = struc_mosaic, core_args = list(),
legend = NULL, legend_args = list(),
main = NULL, sub = NULL, margins = unit(3, "lines"),
title_margins = NULL, legend_width = NULL,
main_gp = gpar(fontsize = 20), sub_gp = gpar(fontsize = 15),
newpage = TRUE, pop = TRUE, return_grob = FALSE,
keep_aspect_ratio = NULL, prefix = "", ...)
Invisibly, an object of class "structable"
corresponding to the
plot. If return_grob
is TRUE
, additionally, the plot as
a grob object is returned in a grob
attribute.
a contingency table in array form, with optional category
labels specified in the dimnames
attribute.
optionally, an array of residuals of the same dimension
as x
(see details).
optionally, an array of expected values of the same dimension
as x
, or alternatively the corresponding independence model specification
as used by loglin
or loglm
(see details).
degrees of freedom passed to the shading functions
used for inference. Will be calculated (and overwritten if
specified) if both expected
and
residuals
are NULL
, or if expected
is given a formula.
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 spacings
).
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 independence model, and else the total
independence model.
a character string indicating the type of
residuals to be computed when none are supplied.
If residuals
is NULL
, residuals_type
must
be one of "pearson"
(default; 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. If residuals
are specified, the value of residuals_type
is just passed
“as is” to the legend function.
a character string indicating whether the observed or the expected values of the table should be visualized.
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, FALSE
means horizontal splits. Default is FALSE.
spacing object, spacing function, or a corresponding
generating function (see details and spacings
).
list of arguments for the spacing-generating function, if specified.
object of class "gpar"
, shading function or a
corresponding generating function (see details and
shadings
). Components of "gpar"
objects are recycled as needed along the last splitting dimension.
Ignored if shade = FALSE
.
list of arguments for the shading-generating function, if specified.
either a logical, or a labeling function, or a corresponding
generating function (see details and labelings
. If
FALSE
or NULL
, no labeling is produced.
list of arguments for the labeling-generating function, if specified.
either a core function, or a corresponding generating
function (see details). Currently, generating functions for
mosaic plots (struc_mosaic
), association plots
(struc_assoc
), and sieve plots
(struc_sieve
) are provided.
list of arguments for the core-generating function, if specified.
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
function, legend defaults to legend_resbased
.
list of arguments for the legend-generating function, if specified.
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.
a character string used for plotting the subtitle.
If sub
is a logical and TRUE
and main
is unspecified, the
name of the object supplied as x
is used.
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 margin of the plot, respectively.
When a numeric vector is supplied, the numbers are interpreted as
"lines"
units. In addition, the unit or numeric vector
may have named arguments
(top, right, bottom, and left), in which
case the non-named arguments specify the default values (recycled as
needed), overloaded by the named arguments.
either an object of class "unit"
of length 2, or
a numeric vector of length 2. The elements are recycled as needed.
The two components specify the top and bottom title margin
of the plot, respectively. The default for each
specified title are 2 lines (and 0 else), except when a
legend is plotted and keep_aspect_ratio
is TRUE
: in
this case, the default values of both margins are set as to align
the heights of legend and actual plot.
When a numeric vector is supplied, the numbers are interpreted as
"lines"
units. In addition, the unit or numeric vector
may have named arguments (top and bottom), in which
case the non-named argument specify the default value (recycled as
needed), overloaded by the named arguments.
An object of class "unit"
of length
1 specifying the width of the legend (if any). Default: 5 lines.
logical indicating whether the generated viewport tree should be removed at the end of the drawing or not.
object of class "gpar"
containing the graphical
parameters used for the main (sub) title, if specified.
logical indicating whether a new page should be created for the plot or not.
logical. Should a snapshot of the display be returned as a grid grob?
logical indicating whether the aspect ratio should be
fixed or not. If unspecified, the default is TRUE
for
two-dimensional tables and FALSE
otherwise.
optional character string used as a prefix for the generated viewport and grob names.
For convenience, list of arguments passed to the labeling-generating function used.
David Meyer David.Meyer@R-project.org
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 core function, the spacing
between the tiles, the shading of the tiles, the labeling, and the
legend, are modularized in graphical appearance control (``grapcon'')
functions and specified as parameters. For
each element foo (= spacing
, labeling
, core
,
or legend
), strucplot
takes two arguments:
foo and foo_args, which can be used to specify the
parameters in the following alternative ways:
Passing a suitable function to foo which subsequently
will be called from strucplot
to compute shadings, labelings,
etc.
Passing a corresponding generating function to foo,
along with parameters passed to foo_args, that generates such a
function. Generating functions must inherit from classes
"grapcon_generator"
and "}foo\code{"
.
Except for the shading functions (shading_bar), passing foo(foo_args) to the foo argument.
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 core 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.).
Meyer, D., Zeileis, A., and Hornik, K. (2006),
The strucplot framework: Visualizing multi-way contingency tables with
vcd.
Journal of Statistical Software, 17(3), 1-48.
tools:::Rd_expr_doi("10.18637/jss.v017.i03") and available as
vignette("strucplot")
.
assoc
,
mosaic
,
sieve
,
struc_assoc
,
struc_sieve
,
struc_mosaic
,
structable
,
doubledecker
,
labelings
,
shadings
,
legends
,
spacings
data("Titanic")
strucplot(Titanic)
strucplot(Titanic, core = 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 DataLab