BAMMtools (version 2.1.0)

addBAMMlegend: Add a color legend to a phylo-rate plot

Description

Add a legend to a phylorate plot, with greater manual control.

Usage

addBAMMlegend(x, direction, side, location = 'topleft', nTicks = 2, shortFrac = 0.02, 
longFrac = 0.3, axisOffset = 0.002, cex.axis = 0.8, labelDist = 0.7, ...)

Arguments

x

a plot.bammdata object.

direction

direction of color ramp. If omitted, then direction is automatically inferred, otherwise can be specified as horizontal or vertical.

side

side for tick marks, see axis documentation. Automatically inferred if omitted.

location

either a location name (see Details), or coordinates for the corners of the bar legend c(xmin, xmax, ymin, ymax).

nTicks

number of tick marks, besides of min and max.

shortFrac

Percent of the plot width range that will be used as the short dimention of the legend. Only applies to preset location options.

longFrac

Percent of the plot width range that will be used as the long dimention of the legend. Only applies to preset location options.

axisOffset

distance from color bar for labels, as a percent of the plot width.

cex.axis

size of axis labels

labelDist

distance from axis to axis labels (passed to mgp)

...

additional parameters to be passed to axis.

Value

• Invisibly returns a list with the following components.
• coords
  2-column matrix of xy coordinates for each color bin in the legend.
• width
  Coordinates for the short dimension of the legend.
• pal
  the color ramp
• tickLocs
  the tick mark locations in plotting units
• labels
  the rate values associated with those tick locations.

Details

A number of predefined locations exist in this function to make it easy to add a legend to a phylorate plot. Preset locations are: topleft, topright, bottomleft, bottomright, left, right, top and bottom. If more fine-tuned control is desired, then a numeric vector of length 4 can be supplied to location, specifying the min x, max x, min y and max y values for the legend. See examples.

See Also

Requires an object created with plot.bammdata.

Examples

data(whales, events.whales)
ephy <- getEventData(whales, events.whales, burnin = 0.25, nsamples = 300)

# plot phylorate with extra margin space
x <- plot.bammdata(ephy, lwd = 2, mar = c(5,4,4,4)) 
# presets
addBAMMlegend(x, location = 'topleft')
addBAMMlegend(x, location = 'bottom')
addBAMMlegend(x, location = 'right')

#fine-tune placement
x <- plot.bammdata(ephy, lwd = 2, mar = c(5,4,4,4)) 
axis(1); axis(2)
addBAMMlegend(x, location = c(-1, -0.5, 40, 80), nTicks = 4)
addBAMMlegend(x, location = c(5, 20, 60, 61), nTicks = 4, side = 3, cex.axis = 0.7)

#addBAMMlegend also automatically detects the use of color.interval
data(primates, events.primates)
ephy <- getEventData(primates, events.primates, burnin=0.25, nsamples = 300, type = 'trait')

x <- plot.bammdata(ephy, breaksmethod = 'linear', color.interval = c(NA, 0.12), lwd = 2)
addBAMMlegend(x, location = c(0, 30, 200, 205), nTicks = 1, side = 3)