table                  package:base                  R Documentation

Cross Tabulation and Table Creation

Description:

     'table' uses the cross-classifying factors to build a contingency
     table of the counts at each combination of factor levels.

Usage:

     table(..., exclude = if (useNA == "no") c(NA, NaN), useNA = c("no", 
         "ifany", "always"), dnn = list.names(...), deparse.level = 1) 

     as.table(x, ...)
     is.table(x)

     ## S3 method for class 'table':
     as.data.frame(x, row.names = NULL, ...,
                   responseName = "Freq")

Arguments:

     ...: one of more objects which can be interpreted as factors
          (including character strings), or a list (or data frame)
          whose components can be so interpreted.  (For 'as.table' and
          'as.data.frame', arguments passed to specific methods.)

 exclude: levels to remove from all factors in '...'. If set to 'NULL',
          it implies 'useNA="always"'.

   useNA: whether to include extra 'NA' levels in the table.

     dnn: the names to be given to the dimensions in the result (the
          _dimnames names_).

deparse.level: controls how the default 'dnn' is constructed.  See
          details.

       x: an arbitrary R object, or an object inheriting from class
          '"table"' for the 'as.data.frame' method.

row.names: a character vector giving the row names for the data frame.

responseName: The name to be used for the column of table entries,
          usually counts.

Details:

     If the argument 'dnn' is not supplied, the internal function
     'list.names' is called to compute the 'dimname names'.  If the
     arguments in '...' are named, those names are used.  For the
     remaining arguments, 'deparse.level = 0' gives an empty name,
     'deparse.level = 1' uses the supplied argument if it is a symbol,
     and 'deparse.level = 2' will deparse the argument.

     Only when 'exclude' is specified and non-NULL (i.e., not by
     default), will 'table' potentially drop levels of factor
     arguments.

     Both 'exclude' and 'useNA' operate on an "all or none" basis. If
     you want to control the dimensions of a multiway table separately,
     modify each argument using 'factor' or 'addNA'

     The 'summary' method for class '"table"' (used for 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).

Value:

     'table()' returns a _contingency table_, an object of 'class'
     '"table"', an array of integer values. Note that unlike S the
     result is always an array, a 1D array if one factor is given.

     'as.table' and 'is.table' coerce to and test for contingency
     table, respectively.

     The 'as.data.frame' method for objects inheriting from class
     '"table"' can be used to convert the array-based representation of
     a contingency table to a data frame containing the classifying
     factors and the corresponding entries (the latter as component
     named by 'responseName').  This is the inverse of 'xtabs'.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'tabulate' is the underlying function and allows finer control. 

     Use 'ftable' for printing (and more) of multidimensional tables. 
     'margin.table', 'prop.table', 'addmargins'.

Examples:

     require(stats) # for rpois and xtabs
     ## Simple frequency distribution
     table(rpois(100,5))
     ## Check the design:
     with(warpbreaks, table(wool, tension))
     table(state.division, state.region)

     # simple two-way contingency table
     with(airquality, table(cut(Temp, quantile(Temp)), Month))

     a <- letters[1:3]
     table(a, sample(a))                    # dnn is c("a", "")
     table(a, sample(a), deparse.level = 0) # dnn is c("", "")
     table(a, sample(a), deparse.level = 2) # dnn is c("a", "sample(a)")

     ## xtabs() <-> as.data.frame.table() :
     UCBAdmissions ## already a contingency table
     DF <- as.data.frame(UCBAdmissions)
     class(tab <- xtabs(Freq ~ ., DF)) # xtabs & table
     ## tab *is* "the same" as the original table:
     all(tab == UCBAdmissions)
     all.equal(dimnames(tab), dimnames(UCBAdmissions))

     a <- rep(c(NA, 1/0:3), 10)
     table(a)
     table(a, exclude=NULL)
     b <- factor(rep(c("A","B","C"), 10))
     table(b)
     table(b, exclude="B")
     d <- factor(rep(c("A","B","C"), 10), levels=c("A","B","C","D","E"))
     table(d, exclude="B")
     print(table(b,d), zero.print = ".")

     ## NA counting:
     is.na(d) <- 3:4
     d. <- addNA(d)
     d.[1:7]
     table(d.) # ", exclude = NULL" is not needed
     ## i.e., if you want to count the NA's of 'd', use
     table(d, useNA="ifany")

     ## Two-way tables with NA counts. The 3rd variant is absurd, but shows
     ## something that cannot be done using exclude or useNA. 
     with(airquality,
        table(OzHi=Ozone > 80, Month, useNA="ifany"))
     with(airquality,
        table(OzHi=Ozone > 80, Month, useNA="always"))
     with(airquality,
        table(OzHi=Ozone > 80, addNA(Month)))

