table {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", stringsAsFactors = TRUE)

### Arguments

`...` | one or 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 for all factors in `...`. If set to `NULL`, it implies `useNA = "always"`. See ‘Details’ for its interpretation for non-factor arguments.
`useNA` | whether to include `NA` values in the table. See ‘Details’.
`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.
`stringsAsFactors` | logical: should the classifying factors be returned as factors (the default) or character vectors?

### 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.

`useNA` controls if the table includes counts of `NA` values: the allowed values correspond to never, only if the count is positive and even for zero counts. This is overridden by specifying `exclude = NULL`. Note that levels specified in `exclude` are mapped to `NA` and so included in `NA` counts.

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`.

It is best to supply factors rather than rely on coercion. In particular, `exclude` will be used in coercion to a factor, and so values (not levels) which appear in `exclude` before coercion will be mapped to `NA` rather than be discarded.

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)))

[Package base version 2.15.1 Index]