sieve                  package:vcd                  R Documentation

_E_x_t_e_n_d_e_d _S_i_e_v_e _P_l_o_t_s

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

     (Extended) sieve displays for n-way contingency tables: plots
     rectangles with areas proportional to the expected cell
     frequencies and filled with a number of squares equal to the
     observed frequencies.  Thus, the densities visualize the
     deviations of the observed from the expected values.

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

     ## Default S3 method:
     sieve(x, condvars = NULL, gp = NULL, shade = NULL,
       legend = FALSE, split_vertical = NULL, direction = NULL, spacing = NULL,
       spacing_args = list(), sievetype = c("observed","expected"),
       main = NULL, sub = NULL, ...)
     ## S3 method for class 'formula':
     sieve(formula, data, ..., main = NULL, sub = NULL, subset = NULL)

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

       x: a contingency table in array form, with optional category
          labels specified in the 'dimnames(x)' attribute.

condvars: vector of integers or character strings indicating
          conditioning variables, if any. The table will be permuted to
          order them first.

 formula: a formula specifying the variables used to create a 
          contingency table from 'data'.  For convenience, conditioning
          formulas can be specified; the conditioning variables will
          then be used first for splitting.  Formulas for sieve
          displays (unlike those for doubledecker plots) have no
          response variable.

    data: either a data frame, or an object of class '"table"' or
          '"ftable"'.

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

   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. If 'shade' is 'NULL' (default), 'gp' is
          used if specified.

sievetype: logical indicating whether rectangles should be filled
          according to 'observed' or 'expected' frequencies.

      gp: object of class '"gpar"', shading function or a corresponding
          generating function (see details of 'strucplot' and
          'shadings'). Components of '"gpar"' objects are recycled as
          needed along the last splitting dimension. The default is a
          modified version of 'shading_Friendly': if 'sievetype' is
          '"observed"', cells with positive residuals are painted red,
          and cells with negative residuals blue. If 'sievetype' is
          '"expected"', the sieves' color is gray. Ignored if 'shade =
          FALSE'.

  legend: either a legend-generating function, a legend function (see
          details of 'strucplot' and 'legends'), or a logical value. If
          'legend' is 'NULL' or 'TRUE' and 'gp' is a function, legend
          defaults to 'legend_resbased'.

split_vertical: vector of logicals of length k, where k is the number
          of margins of 'x' (default: 'FALSE'). 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. Ignored if 'direction' is not
          'NULL'.

direction: character vector of length k, where k is the number of
          margins of 'x' (values are recycled as needed). For each
          component, a value of '"h"' indicates that the tile(s) of the
          corresponding dimension should be split horizontally, whereas
          '"v"' indicates vertical split(s).

 spacing: spacing object, spacing function, or corresponding generating
          function (see 'strucplot' for more information). The default
          is 'spacing_equal' if 'x' has two dimensions, and 
          'spacing_increase' for more dimensions.

spacing_args: list of arguments for the generating function, if
          specified (see 'strucplot' for more information).

main, sub: either a logical, or a character string used for plotting
          the main (sub) title.  If logical and 'TRUE', the name of the
          'data' object is used.

     ...: Other arguments passed to 'strucplot'

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

     'sieve' is a generic function which currently has a default method
     and a formula interface.  Both are high-level interfaces to the
     'strucplot' function, and produce (extended) sieve displays.  Most
     of the functionality is described there, such as specification of
     the independence model, labeling, legend, spacing, shading, and
     other graphical parameters.

     The layout is very flexible: the specification of shading,
     labeling, spacing, and legend is modularized (see 'strucplot' for
     details).

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

     The '"structable"' visualized is returned invisibly.

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

     David Meyer David.Meyer@R-project.org

_R_e_f_e_r_e_n_c_e_s:

     H. Riedwyl & M. Schpbach (1994), Parquet diagram to plot
     contingency tables. In F. Faulbaum (ed.), _Softstat '93: Advances
     in Statistical Software_, 293-299. Gustav Fischer, New York.

     M. Friendly (2000), Visualizing Categorical Data, SAS Institute,
     Cary, NC.

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

     'assoc', 'strucplot', 'mosaic', 'structable', 'doubledecker'

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

     data(HairEyeColor)

     ## aggregate over 'sex':
     (tab <- margin.table(HairEyeColor, c(2,1)))

     ## plot expected values:
     sieve(tab, sievetype = "expected", shade = TRUE)

     ## plot observed table:
     sieve(tab, shade = TRUE)

     ## plot complete diagram:
     sieve(HairEyeColor, shade = TRUE)

     ## an example for the formula interface:
     data(VisualAcuity)
     sieve(Freq ~ right + left,  data = VisualAcuity)

     ## example with observed values in the cells:
     sieve(Titanic, pop = FALSE, shade = TRUE)
     labeling_cells(text = Titanic, gp = gpar(fontface = 2))(Titanic)

