plotRateThroughTime: Plot rates through time

Description

Generates a plot of diversification or phenotypic rate through time with confidence intervals.

Usage

plotRateThroughTime(
  ephy,
  useMedian = TRUE,
  intervals = seq(from = 0, to = 1, by = 0.01),
  ratetype = "auto",
  nBins = 100,
  smooth = FALSE,
  smoothParam = 0.2,
  opacity = 0.01,
  intervalCol = "blue",
  avgCol = "red",
  start.time = NULL,
  end.time = NULL,
  node = NULL,
  nodetype = "include",
  plot = TRUE,
  cex.axis = 1,
  cex.lab = 1.3,
  lwd = 3,
  xline = 3.5,
  yline = 3.5,
  mar = c(6, 6, 1, 1),
  xticks = NULL,
  yticks = NULL,
  xlim = "auto",
  ylim = "auto",
  add = FALSE,
  axis.labels = TRUE
)

Arguments

ephy

Object of class bammdata or bamm-ratematrix.

useMedian

A logical: will plot median if TRUE, mean if FALSE.

intervals

If NULL, no intervals will be plotted, otherwise a vector of quantiles must be supplied (these will define shaded polygons).

ratetype

If 'auto', defaults to speciation (for diversification) or beta (for traits). Can alternatively specify 'netdiv' or 'extinction'.

nBins

Number of time slices used to generate rates through time.

smooth

A logical: whether or not to apply loess smoothing.

smoothParam

Loess smoothing parameter, ignored if smooth = FALSE.

opacity

Opacity of color for interval polygons.

intervalCol

Color for interval polygons.

avgCol

Color for mean/median line (line will not be plotted if avgCol = NULL).

start.time

Start time (in units before present). If NULL, starts at root.

end.time

End time (in units before present). If NULL, ends at present.

node

If supplied, the clade descended from this node will be used or ignored, depending on nodetype.

nodetype

If 'include', rates will be plotted only for the clade descended from node. If 'exclude', the clade descended from node will be left out of the calculation of rates.

plot

A logical: if TRUE, a plot will be returned, if FALSE, the data for the plot will be returned.

cex.axis

Size of axis tick labels.

cex.lab

Size of axis labels.

lwd

Line width of the average rate.

xline

Margin line for placing x-axis label.

yline

Margin line for placing y-axis label.

mar

Passed to par() to set plot margins.

xticks

Number of ticks on the x-axis, automatically inferred if NULL.

yticks

Number of ticks on the y-axis, automatically inferred if NULL.

xlim

Vector of length 2 with min and max times for x axis. X axis is time since present, so if plotting till the present, xlim[2]==0. Can also be 'auto'.

ylim

Vector of length 2 with min and max rates for y axis. Can also be 'auto'.

add

A logical: should rates be added to an existing plot.

axis.labels

A logical: if TRUE, axis labels will be plotted.

Value

If plot = FALSE, then a list is returned with the following components:

poly A list of matrices, where each matrix contains the coordinates that define each overlapping confidence interval polygon.
avg A vector of y-coordinates for mean or median rates used to plot the average rates line.
times A vector of time values, used as x-coordinates in this plot function.

Details

If the input ephy object has been generated by getEventData and is of class bammdata, then start.time, end.time, node, and nodetype can be specified. If the input ephy object has been generated by getRateThroughTimeMatrix and is of class bamm-ratematrix, then those arguments cannot be specified because they are needed to generate the rate matrix, which in this case has already happened.

The user has complete control of the plotting of the confidence intervals. Confidence intervals will not be plotted at all if intervals=NULL. If a single confidence interval polygon is desired, rather than overlapping polygons, then intervals can specify the confidence interval bounds, and opacity should be set to 1 (see examples).

If working with a large dataset, we recommend first creating a bamm-ratematrix object with getRateThroughTimeMatrix and then using that object as input for plotRateThroughTime. This way, the computation of rates has already happened and will not slow the plotting function down, making it easier to adjust plotting parameters.

Examples

Run this code

# NOT RUN {
data(events.whales)
data(whales)
ephy <- getEventData(whales,events.whales)

# Simple plot of rates through time with default settings
plotRateThroughTime(ephy)

# Plot two processes separately with 90% CI and loess smoothing
plotRateThroughTime(ephy, intervals=seq(from=0,0.9,by=0.01), smooth=TRUE,
                    node=141, nodetype='exclude', ylim=c(0,1.2))

plotRateThroughTime(ephy, intervals=seq(from=0,0.9,by=0.01), smooth=TRUE, 
                    node=141, nodetype='include', add=TRUE,
                    intervalCol='orange')

legend('topleft', legend=c('Dolphins','Whales'), col='red',
    fill=c('orange','blue'), border=FALSE, lty=1, lwd=2, merge=TRUE,
           seg.len=0.6)

# Same plot, but from bamm-ratematrix objects
rmat1 <- getRateThroughTimeMatrix(ephy, node=141, nodetype='exclude')
rmat2 <- getRateThroughTimeMatrix(ephy, node=141, nodetype='include')

plotRateThroughTime(rmat1, intervals=seq(from=0,0.9,by=0.01), 
    smooth=TRUE, ylim=c(0,1.2))

plotRateThroughTime(rmat2, intervals=seq(from=0,0.9,by=0.01), 
    smooth=TRUE, add=TRUE, intervalCol='orange')

# To plot the mean rate without the confidence envelope
plotRateThroughTime(ephy,useMedian=FALSE, intervals=NULL)

# To plot the mean rate, with a single 95% confidence envelope, grayscale
plotRateThroughTime(ephy,useMedian=FALSE, intervals=c(0.05,0.95),
    intervalCol='gray70', avgCol='black', opacity=1)

# To not plot, but instead return the plotting data generated in this
# function, we can make plot=FALSE
plotRateThroughTime(ephy, plot=FALSE)
# }