\Header{legend}{Add Legends to Plots}
\keyword{aplot}{legend}
\begin{Usage}
\begin{verbatim}
legend(x, y, legend, fill, col = "black", lty, lwd = 1, pch,
       bty = "o", bg = par("bg"), cex = 1, xjust = 0, yjust = 1,
       x.intersp = NULL, y.intersp = NULL, text.width = NULL,
       merge = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] the x location of the legend.
\item[\texttt{y}] the y location of the legend.
\item[\texttt{legend}] a vector of text values or an \texttt{\Link{expression}}
of length \eqn{\ge 1}{>= 1} to appear in the legend.
\item[\texttt{fill}] if specified, this argument will cause boxes filled
with the specified colors to appear beside the legend text.
\item[\texttt{col}] the color of points or lines appearing in the legend.
\item[\texttt{lty,lwd}] the line types and widths for lines appearing in the
legend.  One of these two \emph{must} be specified for line drawing.
\item[\texttt{pch}] the plotting symbols appearing in the legend, either as
vector of 1-character strings, or one (multi character)
string. \emph{Must} be specified for symbol drawing.
\item[\texttt{bty}] the type of box to be drawn around the legend.
\item[\texttt{bg}] the background color for the legend box.
\item[\texttt{cex}] character expansion factor \bold{relative} to current
\texttt{par("cex")}.
\item[\texttt{xjust}] how the legend is to be justified relative to the legend
x location.  A value of 0 means left justified, 0.5 means centered
and 1 means right justified.
\item[\texttt{yjust}] the same as \texttt{xjust} for the legend y location.
\item[\texttt{x.intersp}] character interspacing factor for horizontal (x)
spacing.
\item[\texttt{y.intersp}] the same as \texttt{x.intersp} for vertical (y) line
distances.
\item[\texttt{text.width}] the width of the legend text in x (\texttt{"user"})
coordinates.
Defaults to the proper value computed by \texttt{\Link{strwidth}(legend)}.
\item[\texttt{merge}] logical; if \texttt{TRUE}, ``merge'' points and lines but
not filled boxes.
\end{ldescription}
\end{Arguments}
\begin{Description}
This function can be used to add legends to plots.  Note that a call
to the function \texttt{\Link{locator}} can be used in place of the \texttt{x}
and \texttt{y} arguments.\end{Description}
\begin{Details}
The default values for \texttt{x.intersp} and \texttt{y.intersp} are
computed from \texttt{Cx <- cex * par('cex')}.

``Attribute'' arguments such as \texttt{col}, \texttt{lty}, \texttt{pch},
etc, are recycled if necessary.\end{Details}
\begin{SeeAlso}
\texttt{\Link{plot}}, \texttt{\Link{barplot}} which uses \texttt{legend()}, and
\texttt{\Link{text}} for more examples of math expressions.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
# Run the example in `?matplot' or the following:
matplot(c(1,8), c(0,4.5), type = "n", xlab = "Length", ylab = "Width",
        main = "Petal and Sepal Dimensions in Iris Blossoms")
leg.txt <- c("    Setosa Petals", "    Setosa Sepals",
             "Versicolor Petals", "Versicolor Sepals")
y.leg <- c( 4, 3, 2.2, 1.5, .9)
cexv  <- c( 1, .8, .6, .4, .25) * if(.Device=="Postscript") 1.2 else 1
for (i in seq(cexv))
  legend(1, y.leg[i], leg.txt, pch = "sSvV", col = c(1, 3), cex = cexv[i])

# `merge = TRUE' for merging lines & points:
x <- seq(-pi, pi, len = 65)
plot(x, sin(x), type = "l", ylim = c(-1.2, 1.8), col = 3, lty = 2)
points(x, cos(x), pch = 3, col = 4)
lines(x, tan(x), type = "b", lty = 1, pch = 4, col = 6)
title("legend(..... lty = c(2, -1, 1), pch = c(-1,3,4), merge = TRUE)",
      cex.main = 1.1)
legend(-1, 1.9, c("sin", "cos", "tan"), col = c(3,4,6),
       lty = c(2, -1, 1), pch = c(-1, 3, 4), merge = TRUE, bg='gray90')

##--- log scaled Examples ------------------------------
leg.txt <- c("a one", "a two")

par(mfrow = c(2,2))
for(ll in c("","x","y","xy")) {
  plot(2:10, log=ll, main=paste("log = '",ll,"'", sep=""))
  abline(1,1)
  lines(2:3,3:4, col=2) #
  points(2,2, col=3)    #
  rect(2,3,3,2, col=4)
  text(c(3,3),2:3, c("rect(2,3,3,2, col=4)",
                     "text(c(3,3),2:3,\"c(rect(...)\")"), adj = c(0,.3))
  legend(list(x=2,y=8), legend = leg.txt, col=2:3, pch=1:2,
         lty=1, merge=T)#, trace=T)
}
par(mfrow=c(1,1))

##-- Math expressions:  ------------------------------
plot(x, sin(x), type="l", col = 2,xlab=expression(phi),ylab=expression(f(phi)))
abline(h=-1:1, v=pi/2*(-6:6), col="gray90")
lines(x, cos(x), col = 3, lty = 2)
ex.cs1 <- expression(plain(sin) * phi,  paste("cos", phi))# 2 ways
legend(-3, .9, ex.cs1, lty=1:2, col=2:3)

x <- rexp(100, rate = .5)
hist(x, main = "Mean and Median of a Skewed Distribution")
abline(v = mean(x),   col=2, lty=2, lwd=2)
abline(v = median(x), col=3, lty=3, lwd=2)
ex12 <- expression(bar(x) == sum(over(x[i], n), i==1, n),
    		   hat(x) == median(x[i], i==1,n))
legend(4.1, 30, ex12, col = 2:3, lty=2:3, lwd=2)
\end{ExampleCode}
\end{Examples}

