Description
Create a contingency table (optionally a sparse matrix) from cross-classifying factors, usually contained in a data frame, using a formula interface.
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 xtabsprint(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 NAs. 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 NAs 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 NAs clearly, and na.print = "NA" maybe advisable instead.
…
further arguments passed to or from other methods.
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.
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 NAs.
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
# 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'sDN <- DF; DN[cbind(6:9, c(1:2,4,1))] <- NA; DNtools::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 --># }Run the code above in your browser using DataLab
