# xtabs

##### Cross Tabulation

Create a contingency table (optionally a sparse matrix) from cross-classifying factors, usually contained in a data frame, using a formula interface.

- Keywords
- category

##### Usage

```
xtabs(formula = ~., data = parent.frame(), subset, sparse = FALSE,
na.action, addNA = FALSE, exclude = if(!addNA) c(NA, NaN),
drop.unused.levels = FALSE)
```# S3 method for xtabs
print(x, na.print = "", …)

##### Arguments

- 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. If unspecified, and`addNA`

is true, this is set to`na.pass`

. When it is`na.pass`

and`formula`

has a left hand side (with counts),`sum(*, na.rm = TRUE)`

is used instead of`sum(*)`

for the counts.- addNA
logical indicating if

`NA`

s should get a separate level and be counted, using`addNA(*, ifany=TRUE)`

and setting the default for`na.action`

.- 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.- x
an object of class

`"xtabs"`

.- na.print
character string (or

`NULL`

) indicating how`NA`

are printed. The default (`""`

) does not show`NA`

s clearly, and`na.print = "NA"`

maybe advisable instead.- …
further arguments passed to or from other methods.

##### Details

There is a `summary`

method for contingency table objects created
by `table`

or `xtabs(*, sparse = FALSE)`

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

For variables in `formula`

which are factors, `exclude`

must be specified explicitly; the default exclusions will not be used.

In R versions before 3.4.0, e.g., when `na.action = na.pass`

,
sometimes zeroes (`0`

) were returned instead of `NA`

s.

##### Value

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`

from package
Matrix.

##### See Also

`table`

for traditional cross-tabulation, and
`as.data.frame.table`

which is the inverse operation of
`xtabs`

(see the `DF`

example below).

`sparseMatrix`

on sparse
matrices in package Matrix.

##### Examples

`library(stats)`

```
# NOT RUN {
## 'esoph' has the frequencies of cases and controls for all levels of
## the variables 'agegp', 'alcgp', and 'tobgp'.
xtabs(cbind(ncases, ncontrols) ~ ., data = esoph)
## Output is not really helpful ... flat tables are better:
ftable(xtabs(cbind(ncases, ncontrols) ~ ., data = esoph))
## In particular if we have fewer factors ...
ftable(xtabs(cbind(ncases, ncontrols) ~ agegp, data = esoph))
## This is already a contingency table in array form.
DF <- as.data.frame(UCBAdmissions)
## Now 'DF' is a data frame with a grid of the factors and the counts
## in variable 'Freq'.
DF
## Nice for taking margins ...
xtabs(Freq ~ Gender + Admit, DF)
## And for testing independence ...
summary(xtabs(Freq ~ ., DF))
## with NA's
DN <- DF; DN[cbind(6:9, c(1:2,4,1))] <- NA; DN
tools::assertError(# 'na.fail' should fail :
xtabs(Freq ~ Gender + Admit, DN, na.action=na.fail))
xtabs(Freq ~ Gender + Admit, DN)
xtabs(Freq ~ Gender + Admit, DN, na.action = na.pass)
## The Female:Rejected combination has NA 'Freq' (and NA prints 'invisibly' as "")
xtabs(Freq ~ Gender + Admit, DN, addNA = TRUE) # ==> count NAs
## Create a nice display for the warp break data.
warpbreaks$replicate <- rep_len(1:9, 54)
ftable(xtabs(breaks ~ wool + tension + replicate, data = warpbreaks))
### ---- Sparse Examples ----
# }
# NOT RUN {
if(require("Matrix")) withAutoprint({
## similar to "nlme"s 'ergoStool' :
d.ergo <- data.frame(Type = paste0("T", rep(1:4, 9*4)),
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)
})
# }
# NOT RUN {
<!-- % only if Matrix is available -->
# }
```

*Documentation reproduced from package stats, version 3.6.0, License: Part of R 3.6.0*