R: Produce a Legend or Key (Grid Function)

draw.leg {IDPmisc} | R Documentation

## Produce a Legend or Key (Grid Function)

### Description

Produces (and possibly draws) a Grid frame grob which is a legend that can be placed in other Grid plots. `draw.leg` is a slightly enhanced version of `draw.key` in package lattice V 0.12-3.

### Usage

    draw.leg(key, draw=FALSE, vp=NULL)

### Arguments

`key` | A list determining the key. See details below and the documentation for `xyplot`.
`draw` | logical, whether the grob is to be drawn.
`vp` | viewport

### Details

Three new components are added to the list `key` of the original code in package lattice V 0.12-3: `between.rows`, `between.title`, `adj.title`. They allow to format the legend in a more flexible way. To ease the use of `draw.leg`, the full description of `draw.key` and the here interesting part of `xyplot` are also included:
The key essentially consists of a number of columns, possibly divided into blocks, each containing some rows. The contents of the key are determined by (possibly repeated) components named “rectangles”, “lines”, “points” or “text”. Each of these must be lists with relevant graphical parameters (see later) controlling their appearance. The `key` list itself can contain graphical parameters, these would be used if relevant graphical components are omitted from the other components.

The length (number of rows) of each such column (except “text”s) is taken to be the largest of the lengths of the graphical components, including the ones specified outside (see the entry for `rep` below for details on this). The “text” component has to have a character or expression vector as its first component, and the length of this vector determines the number of rows.

The graphical components that can be included in `key` (and also in the components named “text”, “lines”, “points” and “rectangles” as appropriate) are:

- `cex=1`

- `col="black"`

- `lty=1`

- `lwd=1`

- `font=1`

- `fontface`

- `fontfamily`

- `pch=8`

- `adj=0`

- `type="l"`

- `size=5`

- `angle=0`

- `density=-1`

`adj`, `angle` and `density` are currently unimplemented. `size` determines the width of columns of rectangles and lines in character widths. `type` is relevant for lines; `"l"` denotes a line, `"p"` denotes a point, and `"b"` and `"o"` both denote both together.

Other possible components of `key` are:

`between`

  numeric vector giving the amount of space (character widths) surrounding each column (split equally on both sides),

`title`

  string or expression giving a title for the key

`rep`

  logical, defaults to `TRUE`. By default, it's assumed that all columns in the key (except the “text”s) will have the same number of rows, and all components are replicated to be as long as the longest. This can be suppressed by specifying `rep=FALSE`, in which case the length of each column will be determined by components of that column alone.

`cex.title`

  cex for the title

`background`

  background color, defaults to default background

`border`

  either a color for the border, or a logical. In the latter case, the border color is black if `border` is `TRUE`, and no border is drawn if it is `FALSE` (the default)

`transparent=FALSE`

  logical, whether key area should have a transparent background

`columns`

  the number of columns column-blocks the key is to be divided into, which are drawn side by side.

`between.columns`

  Space between column blocks, in addition to `between`.

`between.rows`

  New argument: Space between rows.

`between.title`

  New argument: Space between top row and title of legend.

`adj.title`

  New argument: Adjustment of title in respect to body of legend.
  `adj.title = 0` adjusts the title to the left,
  `adj.title = 1` adjusts the title to the right and
  `adj.title = 0.5` (=default) centers the title.

`divide`

  Number of point symbols to divide each line when `type` is `"b"` or `"o"` in `lines`.

### Value

A Grid frame object (that inherits from “grob”)

### Author(s)

Deepayan Sarkar, modified by Rene Locher

### See Also

`xyplot`

### Examples

    require(grid)

    ## Legend 2 cm below and 1 cm left of the upper right corner
    grid.newpage()
    key <- draw.leg(key =
                        list(rectangles = list(col=1:3,
                                 size = 2,
                                 lwd = 0.5),
                             text = list(LETTERS[1:3]),
                             cex = 1.2,
                             between = 2,
                             between.rows = 0.5,
                             between.title = 0.7,
                             title = "component",
                             cex.title = 1.4,
                             transparent = TRUE))

    vp.key <-  viewport(x = convertX(unit(1,"npc")-unit(1,"cm"),"cm"),
                        y = convertY(unit(1,"npc")-unit(2,"cm"),"cm"),
                        width=grobWidth(key),
                        height=grobHeight(key),
                        just=c("right","top"))

    pushViewport(vp.key)
    grid.draw(key)
    popViewport()

    ##----------------------------------------
    ## Legend 1 cm above the lower left corner
    key <- draw.leg(key = list(rectangles = list(col=1:3,
                                 size = 4,
                                 lwd = 0.5),
                      text=list(letters[1:3]),
                      lines=list(col=1:3),
                      cex=2,
                      between=2,
                      between.rows=0.5,
                      between.title=0.7,
                      title = "component",
                      adj.title = 0,
                      cex.title = 2.4,
                      transparent = TRUE))

    vp.key <-  viewport(x = 0,
                        y = unit(1,"cm"),
                        width=grobWidth(key),
                        height=grobHeight(key),
                        just=c("left","bottom"))

    grid.newpage()
    pushViewport(vp.key)
    grid.draw(key)
    popViewport()

[Package IDPmisc version 1.1.20 Index]