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
)

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.

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.

Author

Pascal Title

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

if (FALSE) {
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)}

Run the code above in your browser using DataLab