\HeaderA{table}{Cross Tabulation and Table Creation}{table}
\aliasA{as.data.frame.table}{table}{as.data.frame.table}
\aliasA{as.table}{table}{as.table}
\methaliasA{as.table.default}{table}{as.table.default}
\aliasA{is.table}{table}{is.table}
\aliasA{print.summary.table}{table}{print.summary.table}
\aliasA{summary.table}{table}{summary.table}
\keyword{category}{table}
\begin{Description}\relax
\code{table} uses the cross-classifying factors to build a contingency
table of the counts at each combination of factor levels.
\end{Description}
\begin{Usage}
\begin{verbatim}
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")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] 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 \code{as.table} and
\code{as.data.frame}, arguments passed to specific methods.)
\item[\code{exclude}] levels to remove
from all factors in \code{...}. If set to \code{NULL}, it implies
\code{useNA="always"}.
\item[\code{useNA}] whether to include extra \code{NA} levels in the table.
\item[\code{dnn}] the names to be given to the dimensions in the result (the
\emph{dimnames names}).
\item[\code{deparse.level}] controls how the default \code{dnn} is
constructed.  See details.
\item[\code{x}] an arbitrary \R{} object, or an object inheriting from class
\code{"table"} for the \code{as.data.frame} method.
\item[\code{row.names}] a character vector giving the row names for the data
frame.
\item[\code{responseName}] The name to be used for the column of
table entries, usually counts.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If the argument \code{dnn} is not supplied, the internal function
\code{list.names} is called to compute the \sQuote{dimname names}.  If the
arguments in \code{...} are named, those names are used.  For the
remaining arguments, \code{deparse.level = 0} gives an empty name,
\code{deparse.level = 1} uses the supplied argument if it is a symbol,
and \code{deparse.level = 2} will deparse the argument.

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

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

The \code{summary} method for class \code{"table"} (used for objects
created by \code{table} or \code{\LinkA{xtabs}{xtabs}}) which gives basic
information and performs a chi-squared test for independence of
factors (note that the function \code{\LinkA{chisq.test}{chisq.test}} currently
only handles 2-d tables).
\end{Details}
\begin{Value}
\code{table()} returns a \emph{contingency table}, an object of
\code{\LinkA{class}{class}} \code{"table"}, an array of integer values.
Note that unlike S the result is always an array, a 1D array if one
factor is given.

\code{as.table} and \code{is.table} coerce to and test for contingency
table, respectively.

The \code{as.data.frame} method for objects inheriting from class
\code{"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 \code{responseName}).  This is the inverse of \code{\LinkA{xtabs}{xtabs}}.
\end{Value}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{tabulate}{tabulate}} is the underlying function and allows finer
control. 

Use \code{\LinkA{ftable}{ftable}} for printing (and more) of
multidimensional tables.  \code{\LinkA{margin.table}{margin.table}},
\code{\LinkA{prop.table}{prop.table}}, \code{\LinkA{addmargins}{addmargins}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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)))
\end{ExampleCode}
\end{Examples}

