structable                package:vcd                R Documentation

_S_t_r_u_c_t_u_r_e_d _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 function produces a 'flat' representation of a
     high-dimensional contingency table constructed by recursive splits
     (similar to the construction of mosaic displays).

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

     ## S3 method for class 'formula':
     structable(formula, data,
     direction = NULL, split_vertical = NULL, ..., subset, na.action)
     ## Default S3 method:
     structable(..., direction = NULL, split_vertical = FALSE)

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

 formula: a formula object with possibly both left and right hand sides
          specifying the column and row variables of the flat table.

    data: a data frame, list or environment containing the variables to
          be cross-tabulated, or an object inheriting from class
          'table'.

  subset: an optional vector specifying a subset of observations to be
          used. Ignored if 'data' is a contingency table.

na.action: a function which indicates what should happen when the data
          contain 'NA's. Ignored if 'data' is a contingency table

     ...: R objects which can be interpreted as factors (including
          character strings), or a list (or data frame) whose
          components can be so interpreted, or a contingency table
          object of class '"table"' or '"ftable"'.

split_vertical: logical vector indicating, for each dimension, whether
          it should be split vertically or not (default: 'FALSE').
          Values are recycled as needed. If the argument is of length
          1, the value is alternated for all dimensions. Ignored if
          'direction' is provided.

direction: character vector alternatively specifying the splitting
          direction ('"h"' for horizontal and '"v"' for vertical
          splits).  Values are recycled as needed.  If the argument is
          of length 1, the value is alternated for all dimensions.

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

     This function produces textual representations of mosaic displays,
     and thus 'flat' contingency tables. The formula interface is quite
     similar to the one of 'ftable', but also accepts the 'mosaic'-like
     formula interface (empty left-hand side).  Note that even if the
     'ftable' interface is used, the 'split_vertical' or 'direction'
     argument is needed to specify the _order_ of the horizontal and
     vertical splits. If pretabulated data with a 'Freq' column is
     used, than the left-hand side should be left empty-the 'Freq'
     column will be handled correctly.

     '"structable"' objects can be subset using the '[' and '[['
     operators, using either level indices or names (see examples). The
     corresponding replacement functions are available as well. In
     addition, appropriate 'cbind', 'rbind', 'length', 'dim', and
     'is.na' methods do exist.

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

     An object of class '"structable"', inheriting from class
     '"ftable"', with the splitting information ('"split_vertical"') as
     additional attribute.

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

     David Meyer David.Meyer@R-project.org

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

     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. URL
     http://www.jstatsoft.org/v17/i03/ and available as 
     'vignette("strucplot")'.

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

     'strucplot', 'mosaic', 'ftable'

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

     structable(Titanic)
     structable(Titanic, split_vertical = c(TRUE, TRUE, FALSE, FALSE))
     structable(Titanic, direction = c("h","h","v","v"))
     structable(Sex + Class ~ Survived + Age, data = Titanic)

     ## subsetting of structable objects
     (hec <- structable(aperm(HairEyeColor)))

     ## The "[" operator treats structables as a block-matrix and selects parts of the matrix:
     hec[1]
     hec[2]
     hec[1,c(2,4)]
     hec["Male",c("Blue","Green")]

     ## replacement funcion:
     tmp <- hec
     (tmp[1,2:3] <- tmp[2,c(1,4)])

     ## In contrast, the "[[" operator treats structables as two-dimensional
     ## lists. Indexing conditions on specified levels and thus reduces the dimensionality:

     ## seek subtables conditioning on levels of the first dimension:
     hec[[1]]
     hec[[2]]

     ## Seek subtable from the first two dimensions, given the level "Male"
     ## of the first variable, and "Brown" from the second
     ## (the following two commands are equivalent):
     hec[["Male"]][["Brown"]]
     hec[[c("Male","Brown")]]

     ## Seeking subtables by conditioning on row and/or column variables:
     hec[["Male","Hazel"]]
     hec[[c("Male","Brown"),]]
     hec[[c("Male","Brown"),"Hazel"]]

     ## a few other operations
     t(hec)
     dim(hec)
     dimnames(hec)
     as.matrix(hec)
     length(hec)
     cbind(hec[,1],hec[,3])

     as.vector(hec) ## computed on the _multiway_ table
     as.vector(unclass(hec))

