phylo.spindles function

Plots a phylogenetic tree with spindle-diagrams, optimized for showing taxonomic diversity.

phylo.spindles(
  phylo0,
  occ,
  stat = divdistr_,
  prefix = "sptab_",
  pos = NULL,
  ages = NULL,
  xlimits = NULL,
  ylimits = NULL,
  res = 1,
  weights = 1,
  dscale = 0.002,
  col = add.alpha("black"),
  fill = col,
  lwd = 1,
  lty = 1,
  cex.txt = 1,
  col.txt = add.alpha(col, 1),
  axis = TRUE,
  labels = TRUE,
  txt.y = 0.5,
  txt.x = NULL,
  adj.x = NULL,
  add = FALSE,
  tbmar = 0.2,
  smooth = 0,
  italicize = character()
)

Arguments

• phylo0: A time-calibrated phylogenetic tree to plot with spindle diagrams, or a character vector of taxonomic names for which to plot spindle diagrams.
• occ: Either a list()-object containing taxon-range tables for plotting diversity, or a matrix() or data.frame()-object that contains numerical plotting statistics. If the latter is provided, the default use of divdistr_() is overridden and the function will look for a column named "x" and columns matching the phylogeny tip.labels to plot the spindles.
• stat: Plotting statistic to be passed on to viol(). Defaults to use divdistr_().
• prefix: Prefix for taxon-range tables in occ. Defaults to "sptab_"
• pos: Position at which to draw spindles. If NULL (default), then spindles are drawn at c(1:n) where n is the number of taxa in phylo0.
• ages: Optional matrix with lower and upper age limits for each spindle, formatted like the output of tree.ages() (most commonly the same calibration matrix used to time-calibrate the tree)
• xlimits: Limits for plotting on the x axis.
• ylimits: Limits for plotting on the y axis. If NULL (default) or not a numeric vector of length 2, the y limits are instead constructed from the tbmar parameter and the number of entries in the phylogeny or taxon list.
• res: Temporal resolution of diversity estimation (if occ is a matrix or data.frame containing plotting statistics, this is ignored)
• weights: Weights for diversity estimation. Must have the same length as the range of xlimits divided by res. For details, see divdistr_()
• dscale: Scale value of the spindles on the y axis. Should be adjusted manually to optimize visibility of results.
• col: Color to use for the border of the plotted spindles
• fill: Color to use for the fill of the plotted spindles. Defaults to col.
• lwd: Line width for the plotted spindles.
• lty: Line type for the plotted spindles.
• cex.txt: Adjustment for tip label text size
• col.txt: tip label text color, defaults to be same as col, but with no transparency
• axis: Logical indicating whether to plot (temporal) x axis (defaults to TRUE)
• labels: Logical indicating whether to plot tip labels of phylogeny (defaults to TRUE)
• txt.y: y axis alignment of tip labels
• txt.x: x coordinates for plotting tip labels. Can be a single value applicable to all labels, or a vector of the same length as phylo0$tip.label. If NULL (default), the right margin of the plot is used with right-hand alignment for the text.
• adj.x: Numeric value giving alignment on x axis. If NULL (default) this defaults to 0 (left-aligned) but can also any other adjustment value (e.g. 0.5 for centered, 1 for right-aligned).
• add: Logical indicating whether to add to an existing plot, in which case only the spindles are plotted on top of an existing phylogeny, or not, in which case the phylogeny is plotted along with the spindles.
• tbmar: Top and bottom margin around the plot. Numeric of either length 1 or 2
• smooth: Smoothing parameter to be passed on to divdistr_()
• italicize: Character or numeric vector specifying which labels to italicize, if any.

Returns

A plotted phylogeny with spindle diagrams plotted at each of its terminal branches.

Details

The phylo.spindles() function allows the plotting of a phylogeny with spindle diagrams at each of its terminal branches. Various data can be represented (e.g. disparity, abundance, various diversity measures, such as those output by the divDyn package, etc.) depending on the settings for occ and stat, but the function is optimized to plot the results of divdistr_() and does so by default. If another function is used as an argument to stat, it has to be able to take the sequence resulting from xlimits and res as its first, and occ as its 'table' argument and return a vector of the same length as range(xlimits)/res to be plotted. If occ is a list() object containing multiple dataframes, occurrence datasets or taxon range tables are automatically converted to work with abdistr_() or divdistr_() respectively (if the plot contains a phylogeny). If occ is a matrix or data.frame, the x values must already be converted (e.g. using tsconv()) to match the phylogeny.

Examples

data(archosauria)
data(tree_archosauria)
data(ages_archosauria)
data(diversity_table)
phylo.spindles(tree_archosauria,occ=archosauria,dscale=0.005,ages=ages_archosauria,txt.x=66)
phylo.spindles(tree_archosauria,occ=diversity_table,dscale=0.005,ages=ages_archosauria,txt.x=66)