ftable                 package:base                 R Documentation

Flat Contingency Tables

Description:

     Create ``flat'' contingency tables.

Usage:

     ftable(..., exclude = c(NA, NaN), row.vars = NULL, col.vars = NULL)

Arguments:

     ...: 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"'.

 exclude: values to use in the exclude argument of `factor' when
          interpreting non-factor objects.

row.vars: a vector of integers giving the numbers of the variables, or
          a character vector giving the names of the variables to be
          used for the rows of the flat contingency table.

col.vars: a vector of integers giving the numbers of the variables, or
          a character vector giving the names of the variables to be
          used for the columns of the flat contingency table.

Details:

     `ftable' creates ``flat'' contingency tables.  Similar to the
     usual contingency tables, these contain the counts of each
     combination of the levels of the variables (factors) involved. 
     This information is then re-arranged as a matrix whose rows and
     columns correspond to unique combinations of the levels of the row
     and column variables (as specified by `row.vars' and `col.vars',
     respectively).  The combinations are created by looping over the
     variables in reverse order (so that the levels of the
     ``left-most'' variable vary the slowest).  Displaying a
     contingency table in this flat matrix form (via `print.ftable',
     the print method for objects of class `"ftable"') is often
     preferable to showing it as a higher-dimensional array.

     `ftable' is a generic function.  Its default method,
     `ftable.default', first creates a contingency table in array form
     from all arguments except `row.vars' and `col.vars'. If the first
     argument is of class `"table"', it represents a contingency table
     and is used as is; if it is a flat table of class `"ftable"', the
     information it contains is converted to the usual array
     representation using `as.ftable'.  Otherwise, the arguments should
     be R objects which can be interpreted as factors (including
     character strings), or a list (or data frame) whose components can
     be so interpreted, which are cross-tabulated using `table'. Then,
     the arguments `row.vars' and `col.vars' are used to collapse the
     contingency table into flat form.  If neither of these two is
     given, the last variable is used for the columns.  If both are
     given and their union is a proper subset of all variables
     involved, the other variables are summed out.

     Function `ftable.formula' provides a formula method for creating
     flat contingency tables.

Value:

     `ftable' returns an object of class `"ftable"', which is a matrix
     with counts of each combination of the levels of variables with
     information on the names and levels of the (row and columns)
     variables stored as attributes `"row.vars"' and `"col.vars"'.

See Also:

     `ftable.formula' for the formula interface (which allows a `data =
     .' argument); `read.ftable' for information on reading, writing
     and coercing flat contingency tables; `table' for ``ordinary''
     cross-tabulation; `xtabs' for formula-based cross-tabulation.

Examples:

     ## Start with a contingency table.
     data(Titanic)
     ftable(Titanic, row.vars = 1:3)
     ftable(Titanic, row.vars = 1:2, col.vars = "Survived")
     ftable(Titanic, row.vars = 2:1, col.vars = "Survived")

     ## Start with a data frame.
     data(mtcars)
     x <- ftable(mtcars[c("cyl", "vs", "am", "gear")])
     x
     ftable(x, row.vars = c(2, 4))

