\Header{merge}{Merge Two Data Frames}
\methalias{merge.data.frame}{merge}
\methalias{merge.default}{merge}
\keyword{array}{merge}
\keyword{manip}{merge}
\begin{Description}\relax
Merge two data frames by common columns or row names, or do other
versions of database \dQuote{join} operations.
\end{Description}
\begin{Usage}
\begin{verbatim}
merge(x, y, ...)

## Default S3 method:
merge(x, y, ...)

## S3 method for class 'data.frame':
merge(x, y, by = intersect(names(x), names(y)),
      by.x = by, by.y = by, all = FALSE, all.x = all, all.y = all,
      sort = TRUE, suffixes = c(".x",".y"), ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, y}] data frames, or objects to be coerced to one
\item[\code{by, by.x, by.y}] specifications of the common columns. See Details.
\item[\code{all}] logical; \code{all=L} is shorthand for \code{all.x=L} and
\code{all.y=L}.
\item[\code{all.x}] logical; if \code{TRUE}, then extra rows will be added to
the output, one for each row in \code{x} that has no matching row in
\code{y}.  These rows will have \code{NA}s in those columns that are
usually filled with values from \code{y}.  The default is
\code{FALSE}, so that only rows with data from both \code{x} and
\code{y} are included in the output.
\item[\code{all.y}] logical; analogous to \code{all.x} above.
\item[\code{sort}] logical.  Should the results be sorted on the \code{by}
columns?
\item[\code{suffixes}] character(2) specifying the suffixes to be used for
making non-\code{by} \code{names()} unique.
\item[\code{...}] arguments to be passed to or from methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
By default the data frames are merged on the columns with names they
both have, but separate specifications of the columns can be given by
\code{by.x} and \code{by.y}.  Columns can be specified by name, number
or by a logical vector: the name \code{"row.names"} or the number
\code{0} specifies the row names.  The rows in the two data frames
that match on the specified columns are extracted, and joined
together.  If there is more than one match, all possible matches
contribute one row each.\\
If the \code{by.*} vectors are of length 0, the result, \code{r}, is the
\dQuote{Cartesian product} of \code{x} and \code{y}, i.e.,
\code{dim(r) = c(nrow(x)*nrow, ncol(x) + ncol(y))}.

If \code{all.x} is true, all the non matching cases of \code{x} are
appended to the result as well, with \code{NA} filled in the
corresponding columns of \code{y};  analogously for \code{all.y}.

If the remaining columns in the data frames have any common names,
these have \code{suffixes} (\code{".x"} and \code{".y"} by default)
appended to make the names of the result unique.
\end{Details}
\begin{Value}
A data frame.  The rows are by default lexicographically sorted on the
common columns, but are otherwise in the order in which they occurred
in \code{y}.  The columns are the common columns followed by the
remaining columns in \code{x} and then those in \code{y}.  If the
matching involved row names, an extra column \code{Row.names} is added
at the left, and in all cases the result has no special row names.
\end{Value}
\begin{SeeAlso}\relax
\code{\Link{data.frame}},
\code{\Link{by}},
\code{\Link{cbind}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
authors <- data.frame(
    surname = c("Tukey", "Venables", "Tierney", "Ripley", "McNeil"),
    nationality = c("US", "Australia", "US", "UK", "Australia"),
    deceased = c("yes", rep("no", 4)))
books <- data.frame(
    name = c("Tukey", "Venables", "Tierney",
             "Ripley", "Ripley", "McNeil", "R Core"),
    title = c("Exploratory Data Analysis",
              "Modern Applied Statistics ...",
              "LISP-STAT",
              "Spatial Statistics", "Stochastic Simulation",
              "Interactive Data Analysis",
              "An Introduction to R"),
    other.author = c(NA, "Ripley", NA, NA, NA, NA,
                     "Venables & Smith"))

(m1 <- merge(authors, books, by.x = "surname", by.y = "name"))
(m2 <- merge(books, authors, by.x = "name", by.y = "surname"))
stopifnot(as.character(m1[,1]) == as.character(m2[,1]),
          all.equal(m1[, -1], m2[, -1][ names(m1)[-1] ]),
          dim(merge(m1, m2, by = integer(0))) == c(36, 10))

## "R core" is missing from authors and appears only here :
merge(authors, books, by.x = "surname", by.y = "name", all = TRUE)
\end{ExampleCode}
\end{Examples}

