ltt: Creates lineage-through-time plot (including extinct...

In phytools: Phylogenetic Tools for Comparative Biology (and Other Things)

Creates lineage-through-time plot (including extinct lineages)

Description

Computes and visualizes a lineage through time (LTT) plot, and related measures.

Usage

ltt(tree, ...)
## S3 method for class 'phylo'
ltt(tree, plot=TRUE, drop.extinct=FALSE, log.lineages=TRUE, gamma=TRUE, ...)
## S3 method for class 'multiPhylo'
ltt(tree, drop.extinct=FALSE, gamma=TRUE, ...)
## S3 method for class 'simmap'
ltt(tree, plot=TRUE, log.lineages=FALSE, gamma=TRUE, ...)
## S3 method for class 'multiSimmap'
ltt(tree, gamma=TRUE, ...)
gtt(tree, n=100, ...)
mccr(obj, rho=1, nsim=100, ...)

Arguments

tree	an object of class "phylo", "multiPhylo", "simmap", or "multiSimmap".
plot	a logical value indicating whether or not to create LTT plot.
drop.extinct	logical value indicating whether or not to drop extinct tips from the tree.
log.lineages	logical value indicating whether LTT plot should be on log-linear (default for "phylo" and "multiPhylo" objects) or linear-linear scale.
gamma	logical value indicating whether or not to compute \gamma from Pybus & Harvey (2000; Proc. Roy. Soc. B).
n	for gtt the number of time intervals to use to track \gamma through time.
obj	for mccr an object of class "ltt".
rho	for mccr sampling fraction.
nsim	for mccr number of simulations to use for the MCCR test.
...	other arguments to be passed to plotting methods. See plot.default.

Details

The function ltt computes LTT plot with extant and extinct lineages, and optionally conducts \gamma-test of Pybus & Harvey (2000). The object returned by ltt can be plotted or re-plotted using plot.

For the case in which tree is an object of class "simmap" or "multiSimmap" then the object will contain the number of lineages through time (for each tree, in the case of "multiSimmap" objects) separated by mapped regimes.

The function gtt computes the value of Pybus & Harvey's \gamma statistic through time by slicing the tree at various points - by default in even intervals from the time above the root at which N = 3 to the present day.

The function mccr performs the MCCR test of Pybus & Harvey (2000) which takes into account incomplete taxon sampling in computing a P-value of the \gamma statistic.

Although it is calculated here, it's unclear how to interpret the \gamma-statistic if not all the tips in the tree are contemporaneous.

Value

ltt returns an object of class "ltt" which normally includes the following elements:

times	a vector of branching times.
ltt	a vector of lineages, or a matrix of lineages in each state over time for objects of class "simmap" and "multiSimmap".
gamma	optionally, a value for the \gamma-statistic.
p	two-tailed P-value for the \gamma-test.

If tree is an object of class "multiPhylo", then an object of class "multiLtt" is returned consisting of a list of object of class "ltt".

gtt returns an object of class "gtt".

mccr returns of object of class "mccr".

Author(s)

Liam Revell [e-mail]

References

Pybus, O. G., and P. H. Harvey (2000) Testing macro-evolutionary models using incomplete molecular phylogenies. Proc. R. Soc. Lond. B, 267, 2267-2272.

Revell, L. J. (2024) phytools 2.0: an updated R ecosystem for phylogenetic comparative methods (and other things). PeerJ, 12, e16505.

See Also

gammatest, ltt95

Examples

## set seed
set.seed(99)

## simulate set of random trees
trees<-pbtree(n=100,scale=100,nsim=10)

## create "multiLTT" object
obj<-ltt(trees,plot=FALSE)

## plot "multiLTT" object
plot(obj,log="y",log.lineages=FALSE,
    bty="l")
title(main="LTT plots for 10 pure-birth trees",
    font.main=3)

## simulate single tree
tree<-pbtree(b=1,d=0.25,t=4)

## graph LTT with superimposed tree
obj<-ltt(tree,gamma=FALSE,show.tree=TRUE,
    bty="l",lwd=2)
title(main="LTT plot with superimposed tree",
    font.main=3)
obj

## load dataset
data(anoletree)

## create gamma-through-time plot
anole.gtt<-gtt(anoletree,n=40)
plot(anole.gtt)

phytools documentation built on April 3, 2025, 10:43 p.m.