geiger (version 2.0.11)

dtt: disparity-through-time

Description

calculating and plotting disparity-through-time for a phylogenetic tree and phenotypic data

Usage

disparity(phy=NULL, data, index = c("avg.sq", "avg.manhattan", "num.states"))
dtt(phy, data, index=c("avg.sq", "avg.manhattan", "num.states"),
    mdi.range=c(0,1), nsim=0, CI=0.95, plot=TRUE, calculateMDIp=F)

Value

The function disparity returns the disparity of the supplied data. If given a tree, disparity will return disparities computed for each subtree. The vector of disparities is indexed based on the numeric node-identifier of the subtending subtree (e.g., the root is indexed by N+1, where N is the number of species in the tree; see read.tree).

The function dtt returns elements from the list below:

• dtt is average disparity for clades whose stem crosses each time interval in the tree

• times are times for each value in disparity-through-time calculation; these are just the branching times of the phylogeny

• sim are disparities at time intervals for each simulated dataset

• MDI is the value of the MDI statistic, which is the area between the DTT for the data and the median of the simulations

If results are plotted, the mean DTT from the simulated datasets appears in dashed line and the empirical DTT in solid line.

Arguments

phy

a phylogenetic tree of class 'phylo'

data

a named vector or matrix of continuous trait values, associated with species in phy

index

disparity index to use (see Details)

mdi.range

time range over which to calculate MDI statistic

nsim

number of simulations used to calculate null disparity-through-time plot (see Details)

CI

confidence level from which to plot simulated disparities

plot

whether to plot disparities through time

calculateMDIp

calculate p-value for MDI compared to null; only valid if nsim is not zero

Author

LJ Harmon and GJ Slater

Details

The most complete implementation of dtt (where nsim is greater than 0) carries out the entire disparity-through-time (DTT) procedure described in Harmon et al. 2003, where simulated data are used to construct a null DTT distribution. The function disparity simply computes the morphological disparity for a set of species. Note that for mdi.range, time is relative to a total tree length of 1. The default mdi.range is the entire temporal span of the tree, from 0 (root) to 1 (tips).

For either function, the disparity index can be one of the following:

• avg.sq is average squared Euclidean distance among all pairs of points; this is the most common distance metric for disparity in macroevolution

• avg.manhattan is average Manhattan distance among all pairs of points

• num.states is number of unique character states; this is currently the only option for discrete character data

References

Foote M. 1997. The evolution of morphological diversity. ARES 28:129-152.

Harmon LJ, JA Schulte, JB Losos, and A Larson. 2003. Tempo and mode of evolutionary radiation in iguanian lizards. Science 301:961-964.

Slater GJ, SA Price, F Santini, and MA Alfaro. 2010. Diversity vs disparity and the evolution of modern cetaceans. PRSB 277:3097 -3104.

Examples

if (FALSE) {
geo=get(data(geospiza))

## disparity -- not tree-based
disparity(data=geo$dat) # not tree-based

## cladewise disparities
disparity(phy=geo$phy, data=geo$dat)

## disparity through time of culmen length
dttcul<-dtt(phy=geo$phy, data=geo$dat[,"culmenL"], nsim=100, plot=TRUE)

## disparity through time of entire dataset -- without simulated data
dttgeo<-dtt(phy=geo$phy, data=geo$dat, nsim=0, plot=TRUE)
}