ftable                 package:stats                 R Documentation

Flat Contingency Tables

Description:

     Create 'flat' contingency tables.

Usage:

     ftable(x, ...)

     ## Default S3 method:
     ftable(..., exclude = c(NA, NaN), row.vars = NULL,
            col.vars = NULL)

Arguments:

  x, ...: 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.

     When the arguments are R expressions interpreted as factors,
     additional arguments will be passed to 'table' to control how the
     variable names are displayed; see the last example below.

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

     There are methods for 'as.table' and 'as.data.frame'.

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.
     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.
     x <- ftable(mtcars[c("cyl", "vs", "am", "gear")])
     x
     ftable(x, row.vars = c(2, 4))

     ## Start with expressions, use table()'s "dnn" to change labels
     ftable(mtcars$cyl, mtcars$vs, mtcars$am, mtcars$gear, row.vars = c(2, 4),
            dnn = c("Cylinders", "V/S", "Transmission", "Gears"))

