strucplot                package:vcd                R Documentation

_S_t_r_u_c_t_u_r_e_d _D_i_s_p_l_a_y_s _o_f _C_o_n_t_i_n_g_e_n_c_y _T_a_b_l_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

       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 'loglm' (see details).

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 'spacings').

   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 independence model, and else the total
          independence model.

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 ratio
          chi-squared), or '"FT"' for the Freeman-Tukey residuals. The
          value of this argument can be abbreviated.

    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, 'FALSE' means
          horizontal splits.

 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
          ('struc_assoc') are provided.

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 function, legend defaults to
          'legend_resbased'.

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' margin of the plot, respectively. When a numeric
          vector is supplied, the numbers are interpreted as '"lines"'
          units.  In addition, it 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.

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.

_D_e_t_a_i_l_s:

     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 to foo which subsequently will
           be called from 'strucplot' to compute shadings, labelings,
           etc.

        2.  Passing a corresponding _generating_ function to foo, along
           with parameters passed to foo_args, that generates such a
           function. Generating functions must inherit from class
           '"panel_generator"'.

        3.  Except for the shading functions (shading_bar), passing
           foo(foo_args) to the foo argument.

        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.).

_V_a_l_u_e:

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

_N_o_t_e:

     The created viewports, as well as the tiles and bullets, are named
     and thus can conveniently modified after a plot has been drawn
     (and 'pop = FALSE').

_A_u_t_h_o_r(_s):

     David Meyer David.Meyer@R-project.org

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

     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"))

