legend {base} | R Documentation

## Add Legends to Plots

### Description

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.

### Usage

    legend(x, y, legend, fill, col = "black", lty, lwd, pch,
           angle = NULL, density = NULL,
           bty = "o", bg = par("bg"), pt.bg = NA, cex = 1, xjust = 0, yjust = 1,
           x.intersp = 1, y.intersp = 1, adj = 0,
           text.width = NULL, merge = do.lines && has.pch, trace = FALSE,
           ncol = 1, horiz = FALSE)

### Arguments

`x,y` | the x and y location of the legend. `x` can be a list with `x` and `y` components.
`legend` | a vector of text values or an `expression` of length >= 1 to appear in the legend.
`fill` | if specified, 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 legend.
`lty,lwd` | the line types and widths for lines appearing in the legend. One of these two 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.
`angle` | angle of shading lines.
`density` | the density of shading lines, if numeric and positive.
`bty` | the type of box to be drawn around the legend.
`bg` | the background color for the legend box.
`pt.bg` | the background color for the `points`.
`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 justified, 0.5 means centered and 1 means right justified.
`yjust` | the same as `xjust` for the legend y location.
`x.intersp` | character interspacing factor for horizontal (x) spacing.
`y.intersp` | the same for vertical (y) line distances.
`adj` | numeric of length 1 or 2; the string adjustment for legend text. Useful for y-adjustment when `labels` are plotmath expressions.
`text.width` | the width of the legend text in x (`"user"`) coordinates. Defaults to the proper value computed by `strwidth(legend)`.
`merge` | logical; if `TRUE`, ``merge'' points and lines but not filled boxes. Defaults to `TRUE` if there are points and lines.
`trace` | logical; if `TRUE`, shows how `legend` does all its magical computations.
`ncol` | the number of columns in which to set the legend items (default is 1, a vertical legend).
`horiz` | logical; if `TRUE`, set the legend horizontally rather than vertically (specifying `horiz` overrides the `ncol` specification).

### Details

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

Points are drawn after lines in order that they can cover the line with their background color `pt.bg`, if applicable.

### Value

A (`invisible`) list with list components

`rect` | a list with components `w,h` positive numbers giving width and height of the legend's box. `left,top` x and y coordinates of upper left corner of the box.
`text` | a list with components `x,y` numeric vectors of length `length(legend)`, giving the x and y coordinates of the legend's text(s).

### See Also

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

### Examples

    ## Run the example in `?matplot' or the following:
    leg.txt <- c("Setosa     Petals", "Setosa     Sepals",
                 "Versicolor Petals", "Versicolor Sepals")
    y.leg <- c(4.5, 3, 2.1, 1.4, .7)
    cexv  <- c(1.2, 1, 4/5, 2/3, 1/2)
    matplot(c(1,8), c(0,4.5), type = "n", xlab = "Length", ylab = "Width",
            main = "Petal and Sepal Dimensions in Iris Blossoms")
    for (i in seq(cexv)) {
      text  (1, y.leg[i]-.1, paste("cex=",formatC(cexv[i])), cex=.8, adj = 0)
      legend(3, 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=TRUE)#, trace=TRUE)
    }
    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
    str(legend(-3, .9, ex.cs1, lty=1:2, col=2:3, adj = c(0, .6)))# adj y !

    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))
    str(legend(4.1, 30, ex12, col = 2:3, lty=2:3, lwd=2))

    ## `Filled' boxes -- for more, see example(plotfactor)
    data(PlantGrowth)
    plot(cut(weight, 3) ~ group, data = PlantGrowth,
         col = NULL, density = 16*(1:3))

    ## Using `ncol' :
    x <- 0:64/64
    matplot(x, outer(x, 1:7, function(x, k) sin(k * pi * x)),
            type = "o", col = 1:7, ylim = c(-1, 1.5), pch = "*")
    op <- par(bg="antiquewhite1")
    legend(0, 1.5, paste("sin(",1:7,"pi * x)"), col=1:7, lty=1:7, pch = "*",
           ncol = 4, cex=.8)
    legend(.8,1.2, paste("sin(",1:7,"pi * x)"), col=1:7, lty=1:7, pch = "*",cex=.8)
    legend(0, -.1, paste("sin(",1:4,"pi * x)"), col=1:4, lty=1:4, ncol=2, cex=.8)
    legend(0, -.4, paste("sin(",5:7,"pi * x)"), col=5:7,  pch=24, ncol=2, cex=1.5,
           pt.bg="pink")
    par(op)

    ## point covering line :
    y <- sin(3*pi*x)
    plot(x,y,type="l",col="blue", main = "points with bg & legend(*, pt.bg)")
    points(x,y,pch=21,bg="white")
    legend(.4,1,"sin(c x)",pch=21,pt.bg="white",lty=1, col = "blue")

[Package Contents]