

   AAdddd LLeeggeennddss ttoo PPlloottss

        legend(x, y, legend, fill, col= "black", lty, pch, bty = "o",
               bg = par("bg"), cex = 1, xjust = 0, yjust = 1,
               x.intersp = NULL, y.intersp = NULL, text.width = NULL, merge = FALSE)

   AArrgguummeennttss::

          x: the x location of the legend.

          y: the y location of the legend.

     legend: a vector of text values or an `expression' of
             length >= 1 to appear in the legend.

       fill: if specied, this argument will cause boxes filled
             with the specified colors to appear beside the
             legend text.

        col: the color of points or lines appearing in the leg-
             end.

        lty: the line types for lines appearing in the legend.
             Must be specified for line drawing.

        pch: the plotting symbols appearing in the legend,
             either as vector of 1-character strings, or one
             (multi character) string. Must be specified for
             symbol drawing.

        bty: the type of box to be drawn around the legend.

         bg: the background color for the legend box.

        cex: character expansion factor relative to current
             `par("cex")'.

      xjust: how the legend is to be justified relative to the
             legend x location.  A value of 0 means left justi-
             fied, 0.5 means centered and 1 means right justi-
             fied.

      yjust: the same as `xjust' for the legend y location.

   x.intersp: character interspacing factor for horizontal (x)
             spacing.

   y.intersp: the same as `x.intersp' for vertical (y) line
             distances.

   text.width: the width of the legend text in x (`"user"')
             coordinates.  Defaults to the proper value com-
             puted by `strwidth(legend)'.

      merge: logical; if `TRUE', ``merge'' points and lines but
             not filled boxes.

   DDeessccrriippttiioonn::

        This function can be used to add legends to plots.
        Note that a call to the function `locator' can be used
        in place of the `x' and `y' arguments.

        The default values for `x.intersp' and `y.intersp' are
        computed from `Cx <- cex * par('cex')'.

        ``Attribute'' arguments such as `col', `lty', `pch',
        etc, are recycled if necessary.

   SSeeee AAllssoo::

        `plot', `barplot' which uses `legend()', and `text' for
        more examples of math expressions.

   EExxaammpplleess::

        # 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)
        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')

        ##-- 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,30, ex12, col = 2:3, lty=2:3) # lwd = 2 does not yet work

