xtabs                 package:Matrix                 R Documentation

_C_r_o_s_s _T_a_b_u_l_a_t_i_o_n, _O_p_t_i_o_n_a_l_l_y _S_p_a_r_s_e

_D_e_s_c_r_i_p_t_i_o_n:

     Create a contingency table from cross-classifying factors, usually
     contained in a data frame, using a formula interface.

     This is a fully compatible extension of the standard 'stats'
     package 'xtabs()' function with the added option to produce a
     _sparse_ matrix result via 'sparse = TRUE'.

_U_s_a_g_e:

     xtabs(formula = ~., data = parent.frame(), subset, sparse = FALSE, na.action,
           exclude = c(NA, NaN), drop.unused.levels = FALSE)

_A_r_g_u_m_e_n_t_s:

 formula: a formula object with the cross-classifying variables
          (separated by '+') on the right hand side (or an object which
          can be coerced to a formula).  Interactions are not allowed. 
          On the left hand side, one may optionally give a vector or a
          matrix of counts; in the latter case, the columns are
          interpreted as corresponding to the levels of a variable. 
          This is useful if the data have already been tabulated, see
          the examples below.

    data: an optional matrix or data frame (or similar: see
          'model.frame') containing the variables in the formula
          'formula'.  By default the variables are taken from
          'environment(formula)'.

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

  sparse: logical specifying if the result should be a _sparse_ matrix,
          i.e., inheriting from sparseMatrix.  Only works for two
          factors (since there are no higher-order sparse array classes
          yet). 

na.action: a function which indicates what should happen when the data
          contain 'NA's.

 exclude: a vector of values to be excluded when forming the set of
          levels of the classifying factors.

drop.unused.levels: a logical indicating whether to drop unused levels
          in the classifying factors.  If this is 'FALSE' and there are
          unused levels, the table will contain zero marginals, and a
          subsequent chi-squared test for independence of the factors
          will not work.

_D_e_t_a_i_l_s:

     For (non-sparse) 'xtabs' results, there is a 'summary' method for
     contingency table objects created by 'table' or 'xtabs', which
     gives basic information and performs a chi-squared test for
     independence of factors (note that the function 'chisq.test'
     currently only handles 2-d tables).

     If a left hand side is given in 'formula', its entries are simply
     summed over the cells corresponding to the right hand side; this
     also works if the lhs does not give counts.

_V_a_l_u_e:

     By default, when 'sparse=FALSE', a contingency table in array
     representation of S3 class 'c("xtabs", "table")', with a '"call"'
     attribute storing the matched call.

     When 'sparse=TRUE', a sparse numeric matrix, specifically an
     object of S4 class dgTMatrix.

_S_e_e _A_l_s_o:

     The 'stats' package version 'xtabs' and its references.

_E_x_a_m_p_l_e_s:

     ## See for non-sparse examples:
     example(xtabs, package = "stats")

     ## similar to "nlme"s  'ergoStool' :
     d.ergo <- data.frame(Type = paste("T", rep(1:4, 9*4), sep=""),
                          Subj = gl(9,4, 36*4))
     xtabs(~ Type + Subj, data=d.ergo) # 4 replicates each
     set.seed(15) # a subset of cases:
     xtabs(~ Type + Subj, data=d.ergo[sample(36, 10),], sparse=TRUE)

     ## Hypothetical two level setup:
     inner <- factor(sample(letters[1:25], 100, replace = TRUE))
     inout <- factor(sample(LETTERS[1:5], 25, replace = TRUE))
     fr <- data.frame(inner = inner, outer = inout[as.integer(inner)])
     xtabs(~ inner + outer, fr, sparse = TRUE)