phytools: Phylogenetic Tools for comparative biology (and other things)

Description

phytools provides functions for phylogenetic biology: focused on phylogenetic comparative analysis, but including methods to simulate data and trees, to visualize trees and fitted models, and to analyze and manipulate phylogenetic trees and data.

The complete list of functions can be displayed with library(help=phytools).

The phytools development page is https://github.com/liamrevell/phytools/. More information on phytools can also be found at http://blog.phytools.org or http://www.phytools.org.

If you use phytools (or other packages that depend on phytools) in a publication, please cite it.

The appropriate citation for phytools is listed below or can be obtained using citation("phytools") with the package installed.

Author(s)

Liam J. Revell

Maintainer: Liam J. Revell <liam.revell@umb.edu>

References

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

Conducts correlational D-test from stochastic mapping

Description

Conducts the 'D-test' of Huelsenbeck et al. (2003).

Usage

Dtest(t1, t2, nsim=100, ...)

Arguments

Details

Note that this function has been included without much testing, and so the user should be wary.

Value

An object of class "Dtest".

Author(s)

Liam Revell liam.revell@umb.edu

References

Huelsenbeck, J. P., R. Neilsen, and J. P. Bollback (2003) Stochastic mapping of morphological characters. Systematic Biology, 52, 131-138.

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

See Also

make.simmap, map.overlap

Add an arrow pointing to a tip or node on the tree

Description

Adds an arrow or a set of arrows to a plotted tree.

Usage

add.arrow(tree=NULL, tip, ...)

Arguments

Details

Trees can be plotted using phytools function plotTree, plotSimmap, contMap, densityMap, and ape S3 method plot.phylo.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

nodelabels

Examples

## load tree
data(anoletree)

## plot tree
plotTree(anoletree,type="fan",fsize=0.7,ftype="i")

## add lwd=5 arrows in black
add.arrow(anoletree,tip=c("cuvieri","krugi",
    "pulchellus","poncensis","stratulus",
    "evermanni","cooki","cristatellus",
    "gundlachi","occultus"),lwd=5,arrl=1)

## overlay thinner arrows to create outline effect
add.arrow(anoletree,tip="cuvieri",col="green",
    lwd=3,arrl=1)
add.arrow(anoletree,tip=c("krugi","pulchellus",
    "poncensis"),col="#E4D96F",lwd=3,arrl=1)
add.arrow(anoletree,tip=c("stratulus","evermanni"),
    col="darkgreen",lwd=3,arrl=1)
add.arrow(anoletree,tip=c("cooki","cristatellus",
    "gundlachi"),col="brown",lwd=3,arrl=1)
add.arrow(anoletree,tip="occultus",col="darkgrey",
    lwd=3,arrl=1)
	
## add legend
legend(x="topleft",c("crown-giant","grass-bush","trunk-crown","trunk-ground",
    "twig"),pch=22,pt.bg=c("green","#E4D96F","darkgreen",
    "brown","darkgrey"),cex=0.9,
    pt.cex=2,title="PR ecomorphs",bty="n")
	
## reset plotting parameters
par(mar=c(5.1,4.1,4.1,2.1)) ## reset margins to default

Add color bar to a plot

Description

This function adds a color gradient legend to an existing plot.

Usage

add.color.bar(leg, cols, title=NULL, lims=c(0,1), digits=1, prompt=TRUE,
   lwd=4, outline=TRUE, ...)

Arguments

Details

This function was designed to add a color bar to a plot created by plotBranchbyTrait. A color bar can be added by clicking on a location within the plot (when prompt=TRUE) or by setting prompt=FALSE and supplying x & y coordinates for the object.

The function is also used internally by S3 methods plot.contMap and plot.densityMap, as well as by errorbar.contMap.

Author(s)

Liam Revell liam.revell@umb.edu

References

Revell, L. J. (2013) Two new graphical methods for mapping trait evolution on phylogenies. Methods in Ecology and Evolution, 4, 754-759.

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

See Also

contMap, densityMap, errorbar.contMap, plotBranchbyTrait

Add tip to all edges in a tree

Description

This function adds a tip to all branches of the tree and returns a a list of trees as an object of class "multiPhylo".

Usage

add.everywhere(tree, tip.name)

Arguments

Value

A list of trees as an object of class "multiPhylo". Since the tip can be added to any branch, the length of the list is equal to the number of edges in tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

allFurcTrees, exhaustiveMP

Add tips at random to the tree

Description

This function adds new tips at random to a tree with branch lengths.

Usage

add.random(tree, n=NULL, tips=NULL, edge.length=NULL, order=c("random","input"))

Arguments

Details

If no edge lengths are provided, and the tree is ultrametric, then edge lengths are assigned to keep the tree ultrametric.

The probability that at new tip is added along any branch is directly proportional to the length of the branch.

Note that sometimes the resultant tree plotted with plot.phylo or plotSimmap may display with branches crossing. If so, the tree can be 'untangled' using untangle.

Value

An object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

allFurcTrees, add.everywhere

Add legend to stochastically mapped tree

Description

Adds a legend (by default, interactively) to a plotted stochastic character mapped tree.

Usage

add.simmap.legend(leg=NULL, colors, prompt=TRUE, vertical=TRUE, ...)

Arguments

Details

Redundant with legend, which is much more powerful but somewhat more complicated to use.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

plotSimmap

Add species to genus on a phylogeny or bind simulated species subtrees to a backbone genus tree

Description

add.species.to.genus adds an additional species to a genus on a phylogeny.

genus.to.species.tree simulates pure-birth subtrees and then binds them at a random height along the terminal edge leading to each corresponding genus on a genus-level backbone tree.

Usage

add.species.to.genus(tree, species, genus=NULL, where=c("root","random"))
genus.to.species.tree(tree, species)

Arguments

Details

For add.species.to.genus, if genus contains only one species and where="root", then species will be attached midway along the branch leading to the one species. If where="random" then species will be added at a random position along the edge.

If genus cannot be found in the tree, then the original tree is returned and a warning printed. If the tree is not ultrametric, then the resultant tree may not contain branch lengths and a warning will be printed.

Note that for some cases in which a tree is read in from file, R may initially think it is ultrametric, but then later (as tips are added) decide that it is not due to rounding of the edge lengths when it was written to file. This can most likely be resolved by using force.ultrametric to coerce the tree to be exactly ultrametric (to the maximum numerical precision permitted by R) before adding tips to the tree.

If genus is non-monophyletic then species will be attached to the most inclusive group containing members of genus and a warning will be printed.

Value

An object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

add.random, bind.tip

Computes Akaike weights

Description

Computes Akaike weights based on a set of AIC values.

Usage

aic.w(aic)

Arguments

Details

This function computes Akaike weights from a set of AIC values obtained from fitted models.

It returns an object of class "aic.w" which is just a vector which allows it to be automatically printed with a numerical precision of 8 significant digits.

Value

A vector of Akaike weights.

Author(s)

Liam Revell liam.revell@umb.edu

References

Akaike, H. (1974) A new look at the statistical model identification. IEEE Transactions on Automatic Control, 19, 716-723.

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

Generate all bi- and multifurcating unrooted trees

Description

This function creates all possible unrooted bi- and multifurcating trees and returns a list of trees as an object of class "multiPhylo".

Usage

allFurcTrees(n, tip.label=NULL, to.plot=TRUE)

Arguments

Details

This function should be used with extreme caution for n greater than about 8, as in this case the number of possible trees is extremely large.

Value

A list of trees as an object of class "multiPhylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. 2004. Inferring Phylogenies. Sinauer.

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

See Also

add.everywhere, exhaustiveMP

Examples

## compute & plot all bi- and multifurcating
## trees for six taxa
trees<-allFurcTrees(n=6)

## plot trees
par(mfrow=c(16,15))
nulo<-sapply(trees,plot,type="unrooted",
    no.margin=TRUE)

## reset par
par(mfrow=c(1,1))

Bayesian ancestral character estimation

Description

This function uses Bayesian MCMC to sample from the posterior distribution for the states at internal nodes in the tree.

Usage

anc.Bayes(tree, x, ngen=10000, control=list(), ...)
## S3 method for class 'anc.Bayes'
plot(x, ...)
## S3 method for class 'anc.Bayes'
density(x, ...)

Arguments

Details

plot.anc.Bayes generates a likelihood profile plot of the MCMC by default, but can also create a profile plot for any of the sampled variables by using the optional argument what. For instance, what=40 (or, equivalently, what="40") will create a profile plot of the MCMC for node 40. Additional arguments are passed to plot.

density.anc.Bayes computes a posterior density from the MCMC sample. Like plot.anc.Bayes takes the optional argument what, but unlike plot.anc.Bayes computes the posterior density for the root node by default. The object computed by this function is of class "density" and can be visualized using plot.density. Burn-in (in generations) can be set using the optional argument burnin, otherwise it will be assumed to be 20

The print and summary methods for this object class also return (invisibly) a vector of estimated ancestral states based on a user-supplied burn-in (or 20% of the number of generations of MCMC, if no burn-in is provided). Burn-in can be specified with the optional argument burnin.

Value

anc.Bayes returns an object of class "anc.Bayes" including at least two components:

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

ace, anc.ML, anc.trend, ancr, evol.rate.mcmc, fastAnc

Examples

## set seed
set.seed(77)

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)

## extract character of interest
ln.bodyMass<-log(setNames(mammal.data$bodyMass,
    rownames(mammal.data)))

## run MCMC (should be run at least 1e6 generations)
mcmc<-anc.Bayes(mammal.tree,ln.bodyMass,
    ngen=50000)

## print object to review estimates
print(mcmc,printlen=20)

## plot likelihood trace and root density
par(mfrow=c(2,1))
plot(mcmc,bty="l",main="Likelihood-profile from MCMC",
    font.main=3) ## likelihood-profile
plot(density(mcmc,what=Ntip(mammal.tree)+1,
    burnin=20000),bty="l",
    main="Posterior density for root state of log(body mass)",
    font.main=3)
	
## reset par to default
par(mfrow=c(1,1))

Ancestral character estimation using likelihood

Description

This function estimates the evolutionary parameters and ancestral states for Brownian evolution using likelihood. It is also possible (for model="BM") to allow for missing data for some tip taxa.

Usage

anc.ML(tree, x, maxit=2000, model=c("BM","OU","EB"), ...)

Arguments

Details

Because this function relies on a high dimensional numerical optimization of the likelihood function, fastAnc should probably be preferred for most purposes. If using anc.ML, users should be cautious to ensure convergence.

This issue has been ameliorated in phytools >= 0.2-48 by seeding the ML optimization with the result from fastAnc.

For model="EB" this should also not be a problem as the numerical optimization is performed for only sig2 and r, while the ML values of the ancestral states are obtained during every iteration of the optimization algorithmically using the re-rooting method.

Value

An object of class "anc.ML" with at least the following four elements (if not more, depending on model):

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Schluter, D., Price, T., Mooers, A. O., and Ludwig, D. (1997) Likelihood of ancestor states in adaptive radiation. Evolution 51, 1699-1711.

See Also

ace, anc.Bayes, ancr fastAnc, optim

Examples

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)

## extract character of interest
ln.bodyMass<-log(setNames(mammal.data$bodyMass,
    rownames(mammal.data)))

## estimate ancestral state under BM model
fit.BM<-anc.ML(mammal.tree,ln.bodyMass)

## print results
print(fit.BM)

Ancestral character estimation with a trend

Description

This function estimates the evolutionary parameters and ancestral states for Brownian evolution with a directional trend.

Usage

anc.trend(tree, x, maxit=2000)

Arguments

Details

Note that this will generally only work and produce sensible results for a phylogeny with some non-contemporaneous tips (i.e., a tree with some fossil species).

The function uses optim with method= "L-BFGS-B" internally; however, optimization is only constrained for the sig2 which must be > 0.

Value

An object of class "anc.trend" with the following components:

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

ace, anc.Bayes, anc.ML, optim

Examples

## simulate tree & data using fastBM with a trend (m!=0)
tree<-rtree(n=26,tip.label=LETTERS)
x<-fastBM(tree,mu=4,internal=TRUE)
a<-x[as.character(1:tree$Nnode+Ntip(tree))]
x<-x[tree$tip.label]

## fit no trend model
fit.bm<-anc.ML(tree,x,model="BM")
print(fit.bm)

## fit trend model
fit.trend<-anc.trend(tree,x)
print(fit.trend)

## compare trend vs. no-trend models & estimates
AIC(fit.bm,fit.trend)
layout(matrix(c(3,4,1,2,5,6),3,2,byrow=TRUE),
    heights=c(1.5,3,1.5),widths=c(3,3))
xlim<-ylim<-range(c(a,fit.bm$ace,
    fit.trend$ace))
plot(a,fit.bm$ace,pch=19,
    col=make.transparent("blue",0.5),
    xlab="true ancestral states",
    ylab="ML estimates",
    main=paste("Comparison of true and estimated",
    "\nstates under a no-trend model"),font.main=3,
    cex.main=1.2,bty="l",cex=1.5,
    xlim=xlim,ylim=ylim)
lines(xlim,ylim,lty="dotted")
plot(a,fit.trend$ace,pch=19,
    col=make.transparent("blue",0.5),
    xlab="true ancestral states",
    ylab="ML estimates",
    main=paste("Comparison of true and estimated",
    "\nstates under a trend model"),font.main=3,
    cex.main=1.2,bty="l",cex=1.5,
    xlim=xlim,ylim=ylim)
lines(xlim,ylim,lty="dotted")

## reset par to defaults
par(mfrow=c(1,1))

Ancestral character estimation under the threshold model using Bayesian MCMC

Description

This function uses Bayesian MCMC to estimate ancestral states and thresholds for a discrete character under the threshold model from quantitative genetics (Felsenstein 2012).

Usage

ancThresh(tree, x, ngen=100000, sequence=NULL, method="mcmc", 
   model=c("BM","OU","lambda"), control=list(), ...)

Arguments

Details

According to the threshold model from evolutionary quantitative genetics, values for our observed discrete character are determined by an unseen continuous trait, normally referred to as liability. Every time the value for liability crosses a threshold, the observed discrete character changes in state.

Felsenstein (2012) first had the insight that this model could be used to study the evolution of discrete character traits on a reconstructed phylogenetic tree.

This function uses Bayesian MCMC to sample ancestral liabilities and thresholds for a discrete character evolution under the threshold model.

print and plot S3 methods are now available for the object class "ancThresh".

Value

This function returns an object of class "ancThresh" containing the posterior sample from our analysis, along with other components.

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (2012) A comparative method for both discrete and continuous characters using the threshold model. American Naturalist, 179, 145-156.

Revell, L. J. (2014) Ancestral character estimation under the threshold model from quantitative genetics. Evolution, 68, 743-759.

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

See Also

anc.Bayes, threshBayes

Examples

## Not run: 
## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract character of interest
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))

## run MCMC
mcmc<-ancThresh(sunfish.tree,fmode,ngen=1000000)

## plot results
plot(mcmc,mar=c(0.1,0.1,4.1,0.1))
title(main="Posterior probabilities for node states",
    font.main=3)

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1))
## End(Not run)

Compute marginal or joint ancestral state estimates

Description

By default, ancr computes marginal ancestral states, also known as empirical Bayes posterior probabilities, conditioning on the fitted (or set) model of object.

Can also perform joint ancestral state estimation, if the optional argument type is set to type="joint".

hide.hidden merges hidden states (if any).

Usage

ancr(object, ...)
hide.hidden(object, ...)
## S3 method for class 'ancr'
plot(x, args.plotTree=list(...), args.nodelabels=list(...), ...)

Arguments

Details

If the optional argument tips=TRUE, then the matrix returned contains empirical Bayes posterior probabilities (marginal scaled likelihoods) for both tips and internal nodes. Otherwise (the default) only node marginal states are returned.

If the input object is a set of models (in the form of an anova table), then ancr will compute model-averaged marginal ancestral states (for type="marginal", unless the optional argument weighted=FALSE, in which case only the best-supported model is used.

Value

An object of class "ancr".

For most input obect types, in the case of type="marginal", this object consists of a matrix of marginal (empirical Bayes) probabilities and a likelihood. In the case of type="joint", the object contains a set of most-likely internal node states stored in a data frame.

Author(s)

Liam Revell liam.revell@umb.edu

References

Pagel, M. (1999) The Maximum Likelihood approach to reconstructing ancestral character states of discrete characters on phylogenies. Systematic Biology, 3, 612-622.

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

See Also

fitMk

Examples

## load tree and data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract discrete character (feeding mode)
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))

## fit ARD model
ard_fmode<-fitMk(sunfish.tree,fmode,model="ARD",
    pi="fitzjohn")

## compute ancestral states
anc_fmode<-ancr(ard_fmode)

## plot the results
par(mfrow=c(2,1))
cols<-setNames(c("blue","red"),levels(fmode))
plot(anc_fmode,
    args.plotTree=list(lwd=2,direction="upwards",
        mar=c(0.1,1.1,2.1,1.1),fsize=0.8),
    args.nodelabels=list(piecol=cols),
    args.tiplabels=list(cex=0.3),
    legend="bottomright")
mtext("a) marginal states under ARD model",adj=0)

## fit ER model
er_fmode<-fitMk(sunfish.tree,fmode,model="ER",
    pi="fitzjohn")

## compare models
aov_fmode<-anova(er_fmode,ard_fmode)

## compute model-averaged ancestral states
anc_fmode_model.averaged<-ancr(aov_fmode)
plot(anc_fmode_model.averaged,
    args.plotTree=list(lwd=2,direction="upwards",
        mar=c(0.1,1.1,2.1,1.1),fsize=0.8),
    args.nodelabels=list(piecol=cols),
    args.tiplabels=list(cex=0.3),
    legend="bottomright")
mtext("b) marginal states model-averaging ER & ARD models",
    adj=0)

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1),mfrow=c(1,1))

Phylogenetic datasets

Description

Various phylogenetic datasets for comparative analysis.

Usage

data(anole.data)
data(anoletree)
data(ant.geog)
data(ant.tree)
data(bat.tree)
data(bat_virus.data)
data(betaCoV.tree)
data(bonyfish.data)
data(bonyfish.tree)
data(butterfly.data)
data(butterfly.tree)
data(cordylid.data)
data(cordylid.tree)
data(darter.tree)
data(eel.data)
data(eel.tree)
data(elapidae.tree)
data(flatworm.data)
data(flatworm.tree)
data(liolaemid.tree)
data(mammal.data)
data(mammal.geog)
data(mammal.tree)
data(primate.data)
data(primate.tree)
data(salamanders)
data(sunfish.data)
data(sunfish.tree)
data(tortoise.geog)
data(tortoise.tree)
data(tropidurid.data)
data(tropidurid.tree)
data(vertebrate.data)
data(vertebrate.tree)
data(wasp.data)
data(wasp.trees)
data(whale.tree)

Format

anoletree is an object of class "simmap". anole.data is a data frame.

ant.tree is an object of class "phylo". ant.geog is a vector.

bat.tree and betaCoV.tree are objects of class "phylo". bat_virus.data is a data frame.

bonyfish.tree is an object of class "phylo". bonyfish.data is a data frame.

butterfly.tree is an object of class "phylo". butterfly.data is a data frame.

cordylid.tree is an object of class "phylo". cordylid.data is a data frame.

darter.tree is an object of class "phylo".

eel.tree is an object of class "phylo". eel.data is a data frame.

elapidae.tree is an object of class "phylo".

flatworm.tree is an object of class "phylo". flatworm.data is a data frame.

liolaemid.tree is an object of class "phylo". liolaemid.data is a data frame.

mammal.tree is an object of class "phylo". mammal.data is a data frame. mammal.geog is a numerical matrix.

primate.tree is an object of class "phylo". primate.data is a data frame.

salamanders is an object of class "phylo".

sunfish.tree is an object of class "simmap". sunfish.data is a data frame.

tortoise.tree is an object of class "phylo". tortoise.geog is a data frame.

tropidurid.tree is an object of class "simmap". tropidurid.data is a data frame.

vertebrate.tree is an object of class "phylo". vertebrate.data is a data frame.

wasp.trees is an object of class "multiPhylo". wasp.data is a data frame.

whale.tree is an object of class "phylo".

Details

anoletree is a phylogeny of Greater Antillean anole species with a mapped discrete character - ecomorph class. anole.data is a data frame of morphological characters. Data and tree are from Mahler et al. (2010).

ant.tree is a phylogeny containing 84 species of fungus farming attine ants. ant.geog is a vector containing biogegraphic information for the species of the tree. Both the phylogeny and biogeographic information were originally published by Branstetter et al. (2017).

bat.tree is a ML phylogeny of bats from the families Mormoopidae, Molossidae, and Phyllostomidae, based on GenBank accession numbers reported in Caraballo (2022) and estimated using phangorn. betaCoV.tree is a ML phylogenetic tree of betacoronaviruses based on GenBank accession numbers reported in Caraballo (2022) and estimated using phangorn. bat_virus.data is an association table of host and virus from Caraballo (2022).

butterfly.tree and butterfly.data are a phylogeny and dataset of habitat use in Mycalesina butterflies from Halali et al. (2020). The phylogeny of that study was adapted from one originally published by Brattstrom et al. (2020).

bonyfish.tree and bonyfish.data are a phylogeny and dataset of spawning mode and parental care in bony fishes from Benun Sutton and Wilson (2019). Their phylogenetic tree was adapted from a tree originally published by Betancur-R et al. (2017)

cordylid.tree and cordylid.data are a phylogeny and dataset of morphological traits for three different principal components axes from Broeckhoven et al. (2016).

darter.tree is a phylogeny of 201 species of darter fish (Etheostomatinae) from Near et al. (2011).

eel.tree and eel.data are a phylogeny and dataset of feeding mode and maximum total length from 61 species of elopomorph eels from Collar et al. (2014).

elapidae.tree is a reconstructed phylogeny containing 175 species of snakes of the family Elapidae from Lee et al. (2016).

flatworm.tree and flatworm.data are a phylogeny and dataset of habitat preferences for flatworms from Benitez-Alvarez et al. (2020). flatworm.tree has been made ultrametric using penalized likelihood.

liolaemid.tree and liolaemid.data are a phylogenetic tree and phenotypic trait dataset of lizards from the family Liolaemidae from Esquerre et al. (2019).

mammal.tree and mammal.data are the phylogeny and dataset for mammal body size and home range size from Garland et al. (1992). mammal.geog is a matrix containing geographic coordinates for various of the species in mammal.tree pulled from citizen science observations registered on the iNaturalist web platform.

primate.tree and primate.data are a phylogeny and phenotypic trait dataset from Kirk and Kay (2004).

salamanders is a phylogeny of Plethodon salamanders from Highton and Larson (1979). According to Wikipedia, the genus Plethodon contains 55 species in total.

sunfish.tree and sunfish.data are the phylogeny and dataset for Centrarchidae and buccal morphology (respectively) from Revell and Collar (2009).

tortoise.tree and tortoise.geog are a phylogeny and dataset of geographic coordinates for Galapagos tortoises. The geographic locality information was approximated from Figure 1 of Poulakakis et al. (2020), and the tree was estimated from nucleotide sequence data published with the same study.

tropidurid.tree and tropidurid.data are the phylogeny and bivariate quantitative trait dataset of tropidurid lizards from Revell et al. (2022).

vertebrate.tree is a time-calibrated phylogeny of vertebrates and vertebrate.data is a dataset of phenotypic traits. The phylogeny is from http://www.timetree.org/ (Hedges et al. 2006).

wasp.trees and wasp.data are the phylogeny and host-parasite associations from Lopez-Vaamonde et al. (2001).

whale.tree is a phylogeny of cetaceans originally published in Steeman et al. (2009).

Source

Benitez-Alvarez, L., A. Maria Leal-Zanchet, A. Oceguera-Figueroa, R. Lopes Ferreira, D. de Medeiros Bento, J. Braccini, R. Sluys, and M. Riutort (2020) Phylogeny and biogeography of the Cavernicola (Platyhelminthes: Tricladida): Relicts of an epigean group sheltering in caves? Molecular Phylogenetics and Evolution, 145, 106709.

Benun Sutton, F., and A. B. Wilson (2019) Where are all the moms? External fertilization predicts the rise of male parental care in bony fishes. Evolution, 73, 2451-2460.

Betancur-R, R., E. O. Wiley, G. Arratia, A. Acero, N. Bailly, M. Miya, G. Lecointre, and G. Orti (2017) Phylogenetic classification of bony fishes. BMC Ecology and Evolution, 17, 162.

Branstetter, M. G., A. Jesovnik, J. Sosa-Calvo, M. W. Lloyd, B. C. Faircloth, S. G. Brady, and T. R. Schultz (2017) Dry habitats were crucibles of domestication in the evolution of agriculture in ants. Proceedings of the Royal Society B, 284, 20170095.

Brattstrom, O., K. Aduse-Poku, E. van Bergen, V. French, and P. M. Brakefield (2020) A release from developmental bias accelerates morphological diversification in butterfly eyespots. Proceedings of the National Academy of Sciences, 177, 27474-27480.

Broeckhoven, C., G. Diedericks, C. Hui, B. G. Makhubo, P. le Fras N. Mouton (2016) Enemy at the gates: Rapid defensive trait diversification in an adaptive radiation of lizards. Evolution, 70, 2647-2656.

Caraballo, D. A. (2022) Cross-species transmission of bat coronaviruses in the Americas: Contrasting patterns between alphacoronavirus and betacoronavirus. Microbiology Spectrum, 10, e01411-22.

Collar, D. C., P. C. Wainwright, M. E. Alfaro, L. J. Revell, and R. S. Mehta (2014) Biting disrupts integration to spur skull evolution in eels. Nature Communications, 5, 5505.

Esquerre, D., D. Ramirez-Alvarez, C. J. Pavon-Vazquez, J. Troncoso-Palacios, C. F. Garin, J. S. Keogh, and A. D. Leache (2019) Speciation across mountains: Phylogenomics, species delimitation and taxonomy of the Liolaemus leopardinus clade (Squamata, Liolaemidae). Molecular Phylogenetics and Evolution, 139, 106524.

Garland, T., Jr., P. H. Harvey, and A. R. Ives (1992) Procedures for the analysis of comparative data using phylogenetically independent contrasts. Systematic Biology, 41, 18-32.

Kirk, E. C., and R. F. Kay (2004) The evolution of high visual acuity in the Anthropoidea. In: Ross, C. F., Kay R. F. (Eds), Anthropoid Origins. Developments in Primatology: Progress and Prospects, 539-602. Springer, Boston, MA.

Halali, S., E. van Bergen, C. J. Breuker, P. M. Brakefield, and O. Brattstrom (2020) Seasonal environments drive convergent evolution of a faster pace-of-life in tropical butterflies. Ecology Letters, 24, 102-112.

Hedges, S. B., J. Dudley, and S. Kumar (2006) TimeTree: A public knowledgebase of divergence times among organisms. Bioinformatics, 22, 2971-2972.

Highton, R., and A. Larson (1979) The genetic relationships of the salamanders of the genus Plethodon. Systematic Zoology, 28, 579-599.

Lee, M. S. Y., K. L. Saunders, B. King, and A. Palci (2016) Diversification rates and phenotypic evolution in venomous snakes (Elapidae). Royal Society Open Science, 3, 150277.

Lopez-Vaamonde, C., J. Y. Rasplus, G. D. Weiblen, and J. M. Cook (2001) Molecular phylogenies of fig wasps: Partial cocladogenesis of pollinators and parasites. Molecular Phylogenetics and Evolution, 21, 55-71.

Mahler, D. L, L. J. Revell, R. E. Glor, and J. B. Losos (2010) Ecological opportunity and the rate of morphological evolution in the diversification of Greater Antillean anoles. Evolution, 64, 2731-2745.

Near, T. J., C. M. Bossu, G. S. Bradburd, R. L. Carlson, R. C. Harrington, P. R. Hollingsworth Jr., B. P. Keck, and D. A. Etnier. (2011) Phylogeny and temporal diversification of darters (Percidae: Etheostomatinae). Systematic Biology, 60, 565-595.

Poulakakis, N., J. M. Miller, E. L. Jensen, L. B. Beheregaray, M. A. Russello, S. Glaberman, J. Boore, and A. Caccone. (2020) Colonization history of Galapagos giant tortoises: Insights from mitogenomes support the progression rule. Journal of Zoological Systematics and Evolutionary Research, 58, 1262-1275.

Revell, L. J., and D. C. Collar (2009) Phylogenetic analysis of the evolutionary correlation using likelihood. Evolution, 63, 1090-1100.

Revell, L. J., K. S. Toyama, and D. L. Mahler (2022) A simple hierarchical model for heterogeneity in the evolutionary correlation a phylogenetic tree. PeerJ, 10, e13910.

Steeman, M. E., M. B. Hebsgaard, R. E. Fordyce, S. Y. W. Ho, D. L. Rabosky, R. Nielsen, C. Rahbek, H. Glenner, M. V. Sorensen, and E. Willerslev (2009) Radiation of extant cetaceans driven by restructuring of the oceans. Systematic Biology, 58, 573-585.

Graph a phylogeny using only ANSI characters

Description

Plots a phylogeny in a silly, ANSI graphics style.

Usage

ansi_phylo(tree, vertical=c("|","-"), ...)

Arguments

Value

A plotted tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

plotTree, splinePhylogram

Examples

## load trees
data(salamanders)
data(sunfish.tree)

## plot using defaults
ansi_phylo(salamanders)

## plot using special characters
ansi_phylo(sunfish.tree,vertical="//",horizontal="*",
    xlim=c(0,0.3),fsize=0.9)

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1))

Applies the branch lengths of a reference tree to a target

Description

Applies the branch lengths of a reference tree to a target.

Usage

applyBranchLengths(tree, edge.length)

Arguments

Details

This function applies the set of branch lengths from a reference tree to a target tree while reconciling any mappings (as in read.simmap) with the new branch lengths.

Value

An object of class "phylo" or "simmap".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Convert a fitted Mk model to a Q-matrix

Description

Extracts a Q-matrix from a fitted Mk model.

Usage

as.Qmatrix(x, ...)
## S3 method for class 'fitMk'
as.Qmatrix(x, ...)
## S3 method for class 'Qmatrix'
plot(x, ...)
## S3 method for class 'Qmatrix'
print(x, ...)

Arguments

Details

This function extracts a Q-matrix (in the form of an object of class "Qmatrix") from a fitted Mk model.

Value

An object of class "Qmatrix".

plot.Qmatrix invisibly returns the coordinates of vertices of the plotted Q-matrix.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

fitMk

Conversion to object of class "multiPhylo"

Description

This function converts between object classes.

Usage

as.multiPhylo(x, ...)
## S3 method for class 'multiSimmap'
as.multiPhylo(x, ...)
## S3 method for class 'phylo'
as.multiPhylo(x, ...)

Arguments

Value

An object of class "multiPhylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Average the posterior rates

Description

Internal function for posterior.evolrate.

Usage

ave.rates(tree, shift, tips, sig1, sig2, ave.shift, showTree=TRUE)

Arguments

Value

A list of the rates.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

evol.rate.mcmc, minSplit, posterior.evolrate

Compute an average tree from a set of trees and related operations

Description

Compute average trees or consensus trees by various criteria.

Usage

averageTree(trees, start=NULL, method="quadratic.path.difference",
   tol=1e-12, quiet=FALSE, ...)
ls.consensus(trees, start=NULL, tol=1e-12, quiet=FALSE, ...)
minTreeDist(tree, trees, method="quadratic.path.difference", ...)

Arguments

Details

The function averageTree tries to find the (hypothetical) tree topology and branch lengths that has a minimum distance to all the trees in an input set, according to some user-specified tree distance measure.

The function ls.consensus computes the least-squares consensus tree (Lapointe & Cucumel, 1997) from a set of input trees.

Finally, the function minTreeDist finds the tree in the input set that is a minimum distance to all the other trees in the set. (This contrasts with averageTree which can return a tree not in the input set.)

Value

An object of class "phylo" with edge lengths.

Author(s)

Liam Revell liam.revell@umb.edu

References

Lapointe, F.-J., G. Cucumel (1997) The average consensus procedure: Combination of weighted trees containing identical or overlapping sets of taxa. Systematic Biology, 46, 306-312.

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

Convert object of class "birthdeath" to raw birth & death rates

Description

Converts an object of class "birthdeath" (from birthdeath) to a vector with the ML birth & death rates.

Usage

bd(x)

Arguments

Details

This is now obsolete as phytools now contains functions to fit birth-death and pure-birth diversification models from trees (fit.bd and fit.yule) that also take into account incomplete sampling fraction.

Value

A vector.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

birthdeath, fit.bd, fit.yule

Attaches a new tip to a tree

Description

Adds a new tip to the tree.

Usage

bind.tip(tree, tip.label, edge.length=NULL, where=NULL, position=0,
   interactive=FALSE, ...)

Arguments

Details

If the tree is ultrametric and no branch length is specified, then edge.length is scaled so that the tree remains ultrametric after the new tip is added.

Wrapper function for ape bind.tree. Note that interactive=TRUE works only for right-facing phylograms.

Value

An object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Examples

## set seed
set.seed(123)

## subdivide plotting device
par(mfrow=c(3,1))

## generate tree
tree<-pbtree(b=0.1, n=10)

## plot original tree
plotTree(tree,mar=c(2.1,0.1,2.1,0.1))
axisPhylo()
mtext("a)",adj=0)

## add an extant tip ("t_extant") sister to taxon 't5'
## with divergence time of 4.5 Ma
node<-which(tree$tip.label=="t5")
tree<-bind.tip(tree, tip.label="t_extant",
    where=node, position=4.5)

## re-plot to see the result
plotTree(tree,mar=c(2.1,0.1,2.1,0.1))
axisPhylo()
mtext("b)",adj=0)

## add an extinct tip ("t_extinct") sister to 't2' with
## divergence time of 7.8 Ma and duration (edge length) of
## 3.3 Ma
node<-which(tree$tip.label=="t2")
tree<-bind.tip(tree, tip.label="t_extinct", where=node,
    position=7.8, edge.length=3.3)

## re-plot to see the result
plotTree(tree,mar=c(2.1,0.1,2.1,0.1))
axisPhylo()
mtext("c)",adj=0)

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1),mfrow=c(1,1))

Binds two trees of class "simmap"

Description

This function grafts tree y onto tree x at node where.

Usage

bind.tree.simmap(x, y, where="root")

Arguments

Details

This function wraps around bind.tree for objects of class "simmap"; however it presently only allows y to be grafted at a node of x and it does not allow y to possess a root edge.

Value

An object of class "simmap".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Simulates and visualizes discrete-time Brownian evolution on a phylogeny

Description

Conducts a discrete-time Brownian motion simulation on an input tree, plots the outcome, and returns the tip and internal node states to the user as a named vector.

Usage

bmPlot(tree, type="BM", anc=0, sig2=1/1000, ngen=1000, ...)

Arguments

Details

The function will first rescale and round the branch lengths to integer length, if they are not already in integer values. If integer branch lengths are provided, the user should also set ngen to be equal to the total height of the tree in generations (and thus avoid rescaling).

For type="threshold" the visualization is of the threshold model (Felsenstein 2012), in which the evolving character is liability and the segments of evolution are colored by their value for the threshold trait. If type="threshold" is used, the function requires at least one addition input: thresholds, a vector containing the ordered thresholds between states. The user can also provide the colors for plotting in colors. Note that one more color than threshold should be provided as one threshold implies two states; two thresholds, three states; etc. If no value for colors is provided, the function will recycle a set of four colors up to the number of times required by thresholds. Finally, the optional argument return.tree=TRUE will tell the function to return a list with the tip and note states and an object of class "phylo" with (for type="threshold"), the state for the threshold model through time mapped on the branches of the tree in discrete time.

Value

This function conducts and plots discrete time Brownian simulation and returns a vector containing the simulated states at internal nodes and tips of the tree.

It also returns, by default (although this can be turned off) a tree with the branch lengths in discrete time and with a mapped discrete character (for type="threshold").

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (2012) A comparative method for both discrete and continuous characters using the threshold model. American Naturalist, 179, 145-156.

Revell, L. J. (2014) Ancestral character estimation under the threshold model from quantitative genetics. Evolution, 68, 743-759.

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

See Also

fastBM, pbtree, phenogram, threshBayes

Examples

## set seed
set.seed(999)

## plot BM simulation on 12 taxon tree
tree<-pbtree(n=12)
par(mfrow=c(1,2),mar=c(5.1,4.1,4.1,0.1))
x<-bmPlot(tree,bty="l")
plotTree(tree,direction="upwards",
    mar=c(5.1,0.1,4.1,1.1),ftype="off")

## reset par to default values
par(mfrow=c(1,1),mar=c(5.1,4.1,4.1,2.1))

## plot simulation of a threshold character
par(mfrow=c(1,2),mar=c(5.1,4.1,4.1,0.1))
tt<-bmPlot(tree,type="threshold",thresholds=c(0,1,2),
    bty="l")
plot(tt$tree,direction="upwards",
    mar=c(5.1,0.1,4.1,1.1),ftype="off",
    colors=setNames(c("black","red","blue"),
    letters[1:3]),lwd=3)

## reset par to default values
par(mfrow=c(1,1),mar=c(5.1,4.1,4.1,2.1))

Fits bounded and wrapped Brownian motion models

Description

Fits a bounded Brownian motion model using the discrete approximation of Boucher & Demery (2016), or the "wrapped" or circular model of Juhn et al. (In review).

Usage

	bounded_bm(tree, x, lims=NULL, ...)

Arguments

Details

Optional arguments include (but are not limited to): parallel, defaults to parallel=FALSE; df, to adjust the degrees of freedom of the model, depending on whether or not the bounds have been set from the observed data; levs, number of levels for the discretization (defaults to levs=200); and wrapped, logical indicating whether to fit the "circular" or wrapped model, instead of the standard bounded model (defaults to wrapped=FALSE).

Value

An object of class "bounded_bm".

Author(s)

Liam Revell liam.revell@umb.edu

References

Boucher, F. C., and V. Demery (2016) Inferring bounded evolution in phenotypic characters from phylogenetic comparative data. Systematic Biology, 65, 651-661.

Juhn, M., K. Martinet, F. Boucher, A. Schultz, L. Harmon, K. Burns, and M. Alfaro (In review) A wrapped Brownian motion model for the evolution of color.

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

See Also

fitMk, fitmultiBM, fitThresh

Examples

## Not run: 
## load tree and data
data(eel.tree)
data(eel.data)

## extract trait of interval
maxTL<-setNames(eel.data$Max_TL_cm,
    rownames(eel.data))

## fit bounded model
eel_bounded<-bounded_bm(eel.tree,maxTL,levs=200,
    parallel=TRUE,lims=range(maxTL))

## fit unbounded model
eel_unbounded<-bounded_bm(eel.tree,maxTL,levs=200,
    parallel=TRUE)

## compare models using AIC
AIC(eel_bounded,eel_unbounded)
## End(Not run)

Animation of branching random diffusion

Description

This function creates an animation of branching random diffusion (i.e., Brownian motion evolution with speciation).

Usage

branching.diffusion(sig2=1, b=0.0023, time.stop=1000, ylim=NULL, 
   smooth=TRUE, pause=0.02, record=NULL, path=NULL, ...)

Arguments

Details

For animation to be recorded to file, the function requires the package animation as well as a video renderer.

Value

An animated plot and (optionally) a recorded video file.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

bmPlot, fastBM

Likelihood test for rate variation in a continuous trait

Description

Fits a multi-rate Brownian motion evolution model using maximum likelihood.

Usage

brownie.lite(tree, x, maxit=2000, test="chisq", nsim=100, se=NULL, ...)

Arguments

Details

This function takes an object of class "phylo" or class "simmap" with a mapped binary or multi-state trait (see read.simmap) and data for a single continuously valued character. It then fits the Brownian rate variation ("noncensored") model of O'Meara et al. (2006; Evolution). This is also the basic model implemented in Brian O'Meara's Brownie software.

Sampling error in the estimation of species means can also be accounted for by assigning the vector se with the species specific sampling errors for x.

Value

An object of class "brownie.lite" containing the following elements:

Author(s)

Liam Revell liam.revell@umb.edu

References

O'Meara, B. C., C. Ane, M. J. Sanderson, and P. C. Wainwright (2006) Testing for different rates of continuous trait evolution using likelihood. Evolution, 60, 922-933.

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

See Also

brownieREML, evol.vcv, ratebytree

Examples

## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract character of interest
buccal.length<-setNames(sunfish.data$buccal.length,
    rownames(sunfish.data))

## fit model
multiBM.fit<-brownie.lite(sunfish.tree,
    buccal.length)

## print fitted model
print(multiBM.fit)

REML version of brownie.lite

Description

Fits a multi-rate Brownian motion evolution model using REML. (See brownie.lite for more details.)

Usage

brownieREML(tree, x, maxit=2000, ...)

Arguments

Details

This function takes an object of class "phylo" or an object of class "simmap" with a mapped binary or multi-state trait (see read.simmap) and data for a single continuously valued character. It then uses restricted maximum likelihood (REML) to fit the Brownian rate variation ("noncensored") model of O'Meara et al. (2006; Evolution). This function is similar to brownie.lite but uses REML (which is faster and unbiased) instead of ML. REML optimization takes advantage of Felsenstein's (1985) contrasts algorithm.

Value

An object of class "brownieREML" containing the following components:

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (1985) Phylogenies and the comparative method. American Naturalist, 125, 1-15.

O'Meara, B. C., C. Ane, M. J. Sanderson, and P. C. Wainwright (2006) Testing for different rates of continuous trait evolution using likelihood. Evolution, 60, 922-933.

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

See Also

brownie.lite, evol.vcv, evol.rate.mcmc, ratebytree

Examples

## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract character of interest
gape.width<-setNames(sunfish.data$gape.width,
    rownames(sunfish.data))

## fit model
multiBM.reml<-brownieREML(sunfish.tree,
    gape.width)

## print fitted model
print(multiBM.reml)

Add labels to subtrees of a plotted phylogeny

Description

This function adds clade labels to a plotted tree.

Usage

cladelabels(tree=NULL, text, node, offset=NULL, wing.length=NULL, cex=1,
   orientation="vertical")
arc.cladelabels(tree=NULL, text, node=NULL, ln.offset=1.02,
   lab.offset=1.06, cex=1, orientation="curved", stretch=1, ...)

Arguments

Details

cladelabels presently works only for rightward facing plotted phylogenies - but no warning will be returned if your tree does not conform to this requirement!

arc.cladelabels is designed to do a similar thing to cladelabels, but for plotted fan trees. This function checks to ensure that the most recently plotted tree was plotted with type="fan" style.

Author(s)

Liam Revell liam.revell@umb.edu

References

Paradis, E., J. Claude, and K. Strimmer (2004) APE: Analyses of phylogenetics and evolution in R language. Bioinformatics, 20, 289-290.

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

See Also

nodelabels

Collapse a subtree to a star phylogeny

Description

Collapses a subtree to a star.

Usage

collapse.to.star(tree, node)

Arguments

Details

If the tree has edge lengths, the function will keep the tips at the same height above the root as in the original tree.

If node is the global root of the tree a star phylogeny will be created.

Value

An object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

splitTree, starTree

Interactive tree visualizer

Description

Function creates an interactive visualization of collapsing & expanding clades on the tree.

Usage

collapseTree(tree, ...)

Arguments

Details

Function first plots a fan style tree, and then the user collapses node on the tree by clicking on them. Collapsed nodes are collapsed to the common ancestor of the clade. Nodes that have been collapsed can also be expanded by clicking. Right-click (or select Finish button in RStudio) to end.

Note, for the animation to work probably when run in the RStudio IDE the "zoom" level should be set to 100%.

Value

Returns the final plotted tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

plotTree, plotSimmap

Examples

## Not run: 
## load phylogeny
data(liolaemid.tree)

## run collapseTree
pruned<-collapseTree(liolaemid.tree,fsize=0.5)

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1))
## End(Not run)

Compares two chronograms with precisely matching nodes in a visual manner

Description

Creates a visual comparison of two chronograms that differ in edge lengths but not topology.

Usage

compare.chronograms(t1, t2, ...)

Arguments

Details

This function plots two trees, with semi-transparent colors by default, & uses arrows to highlight differences in depth of corresponding nodes between the trees.

Value

Function creates a plot.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Compute consensus edges for a tree under some criterion

Description

Computes consensus edge lengths from a set of input trees using multiple methods.

Usage

consensus.edges(trees, method=c("mean.edge","least.squares"), ...)

Arguments

Value

An object of class "phylo" with edge lengths.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Map continuous trait evolution on the tree

Description

Projects the observed and reconstructed values of a continuous trait onto the edges of a tree using a color gradient.

Usage

contMap(tree, x, res=100, fsize=NULL, ftype=NULL, lwd=4, legend=NULL,
   lims=NULL, outline=TRUE, sig=3, type="phylogram", direction="rightwards", 
   plot=TRUE, ...)
## S3 method for class 'contMap'
plot(x, ...)
errorbar.contMap(obj, ...)

Arguments

Details

Function plots a tree with a mapped continuous character.

The mapping is accomplished by estimating states at internal nodes using ML with fastAnc, and then interpolating the states along each edge using equation [2] of Felsenstein (1985). This makes these interpolated values equal to the maximum likelihood estimates under a Brownian evolutionary process.

The default color palette is not recommended as it is not colorblind friendly and does not render well into gray scale; however, this can be updated using the helper function setMap.

errorbar.contMap adds error bars to an existing plot.

Value

Plots a tree. An object of class "contMap" is returned invisibly.

errorbar.contMap adds colorful error bars to a plotted tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (1985) Phylogenies and the comparative method. American Naturalist, 125, 1-15.

Revell, L. J. (2013) Two new graphical methods for mapping trait evolution on phylogenies. Methods in Ecology and Evolution, 4, 754-759.

Revell, L. J. (2014) Graphical methods for visualizing comparative data on phylogenies. Chapter 4 in Modern phylogenetic comparative methods and their application in evolutionary biology: Concepts and practice (L. Z. Garamszegi ed.), pp. 77-103.

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

Revell, L. J., K. Schliep, E. Valderrama, and J. E. Richardson (2018) Graphs in phylogenetic comparative analysis: Anscombe's quartet revisited. Methods in Ecology and Evolution, 9, 2145-2154.

See Also

anc.ML, densityMap, fastAnc, plotSimmap

Examples

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)

## extract character of interest
ln.bodyMass<-log(setNames(mammal.data$bodyMass,
    rownames(mammal.data)))

## create "contMap" object
mammal.contMap<-contMap(mammal.tree,
    ln.bodyMass,plot=FALSE,res=200)

## change color scheme
mammal.contMap<-setMap(mammal.contMap,
    c("white","#FFFFB2","#FECC5C","#FD8D3C",
        "#E31A1C"))

## plot object
plot(mammal.contMap,fsize=c(0.7,0.8),
    leg.txt="log(body mass)")

## reset margins to default
par(mar=c(5.1,4.1,4.1,2.1)) 

Creates a co-phylogenetic plot

Description

Visualize co-phylogenetic trees by multiple methods.

Usage

cophylo(tr1, tr2, assoc=NULL, rotate=TRUE, ...)
## S3 method for class 'cophylo'
plot(x, ...)
cotangleplot(tr1, tr2, type=c("cladogram","phylogram"),
   use.edge.length=TRUE, tangle=c("both","tree1","tree2"), ...)

Arguments

Details

cophylo an object of class "cophylo" or, in the case of plot.cophylo, plots that object. The function can (optionally) first attempt to rotate the nodes of both trees to optimize vertical matching of tips.

If no matrix of associations, assoc, is provided, then cophylo will look for exact matches of tip labels between trees.

cotangleplot creates a co-phylogenetic plot in which the edges of the matched trees are crossing and is designed to be used only on phylogenies with matching tip labels.

Value

An object of class "cophylo" which includes the following components or a pair of plotted facing phylogenies with links between tips as specified in assoc.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

cophyloplot, plotSimmap

Examples

## load data from Lopez-Vaamonde et al. (2001)
data(wasp.trees)
data(wasp.data)

## create co-phylogenetic object
wasp.cophylo<-cophylo(wasp.trees[[1]],wasp.trees[[2]],
    assoc=wasp.data)

## plot co-phylogenies
plot(wasp.cophylo,link.type="curved",link.lwd=4,
    link.lty="solid",link.col=make.transparent("red",
        0.25))

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1))

Conducts a statistical test of cospeciation between two trees

Description

Test for cospeciation based on tree distance.

Usage

cospeciation(t1, t2, distance=c("RF","SPR"),
   method=c("simulation","permutation"), assoc=NULL,
   nsim=100, ...)
## S3 method for class 'cospeciation'
plot(x, ...)
## S3 method for class 'cospeciation'
print(x, ...)

Arguments

Details

This function conducts a test for cospeciation based on tree distance, applying a distance metric selected by the user.

Note that this method should be prone to be quite liberal as the null hypothesis is no similarity whatsoever between the two trees!

Value

An object of class "cospeciation", which includes the test-statistic, the null distribution, and a p-value for the test of the null hypothesis of no topological similarity between the two trees.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

cophylo

Examples

## load data from Lopez-Vaamonde et al. (2001)
data(wasp.trees)
data(wasp.data)

## test for cospeciation
wasp.cosp<-cospeciation(wasp.trees[[1]],wasp.trees[[2]],
    assoc=wasp.data)

## print results
print(wasp.cosp)

## plot null distribution & test statistic
plot(wasp.cosp)
title(main=paste("Simulated distribution of RF distances\n",
    "between unassociated trees"),font.main=3)

Counts the number of character changes on a object of class "simmap" or "multiSimmap"

Description

Count the number of changes of different types on a stochastically mapped trees or set of trees (objects of class "simmap" or "multiSimmap").

Usage

countSimmap(tree, states=NULL, message=TRUE)

Arguments

Details

This function takes a tree or a set of trees with a mapped discrete character (that is, an object of class "simmap" or "multiSimmap"), and computes the total number of character changes as well as the number of character changes between all states.

Value

A list with up to three elements: N is an integer value giving the total number of character changes on the tree; Tr gives the number of of transitions between row and column states (or a matrix containing both N and the transitions between states, in rows, for an object of class "multiPhylo"); and (optionally) message contains an explanatory message about the function output.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Examples

## load anole tree with ecomorphs mapped
data(anoletree)
anoletree

## countSimmap
countSimmap(anoletree)

Generates (or simulates) a 'changes through time' plot from a set of stochastic map character histories

Description

Create a 'changes through time' plot from a "multiSimmap" object.

Usage

ctt(trees, segments=20, ...)
sim.ctt(tree, Q, anc=NULL, nmaps=100, ...)
sim.multiCtt(tree, Q, anc=NULL, nmaps=100, nsim=100, ...)

Arguments

Details

This function generates a 'changes through time' plot in the style of a lineage-through-time (LTT) plot. It shows the mean rate or the mean number of changes per unit time from a set of stochastic character map trees.

Value

An object of class "ctt" or "multiCtt".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

ltt

Computes a posterior distribution for the number and types of changes on the tree

Description

S3 methods to summarize the results of one or more stochastic maps.

Usage

## S3 method for class 'multiSimmap'
density(x, ...)
## S3 method for class 'changesMap'
plot(x, ...)

Arguments

Details

density.multiSimmap method="changes" (the default) results in a posterior distribution of the number & types of changes on the tree.

If the package coda has been installed, then the function HPD.interval is used to compute a 95% high probability density interval for the number of changes of each type on the tree. Otherwise, the central 95% of the posterior sample is returned as an estimate of the 95% HPD interval for each change type.

The method also computes the full posterior density for each change type using a bandwidth specified by the user.

method="densityMap" computes a standard "densityMap" object, and thus only permits binary characters.

plot.changesMap plots the posterior density returned by density.multiSimmap for method= "changes".

Value

For method="changes" density.multiSimmap returns an object of class "changesMap".

For method="densityMap" density.multiSimmap returns an object of class "densityMap".

plot.changesMap generates a plot.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Plot posterior density of stochastic mapping on a tree

Description

Visualize posterior probability density from stochastic mapping using a color gradient on the tree.

Usage

densityMap(trees, res=100, fsize=NULL, ftype=NULL, lwd=3, check=FALSE,
   legend=NULL, outline=FALSE, type="phylogram", direction="rightwards",
   plot=TRUE, ...)
## S3 method for class 'densityMap'
plot(x, ...)

Arguments

Details

Function plots a tree with the posterior density for a mapped character from stochastic character mapping on the tree. Since the mapped value is the probability of being in state "1", only binary [0,1] characters are allowed.

Value

Plots a tree and returns an object of class "densityMap" invisibly.

Author(s)

Liam Revell liam.revell@umb.edu

References

Bollback, J. P. (2006) Stochastic character mapping of discrete traits on phylogenies. BMC Bioinformatics, 7, 88.

Huelsenbeck, J. P., R. Neilsen, and J. P. Bollback (2003) Stochastic mapping of morphological characters. Systematic Biology, 52, 131-138.

Revell, L. J. (2013) Two new graphical methods for mapping trait evolution on phylogenies. Methods in Ecology and Evolution, 4, 754-759.

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

See Also

make.simmap, plotSimmap, read.simmap

Examples

## load tree and data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract discrete character (feeding mode)
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))
	 
## fit discrete character models
sunfish_er<-fitMk(sunfish.tree,fmode,model="ER")

## do stochastic mapping
smap.trees<-simmap(sunfish_er)

## compute "densityMap" object
sunfish.dmap<-densityMap(smap.trees,plot=FALSE,
    res=100)
	
## re-color
sunfish.dmap<-setMap(sunfish.dmap,hcl.colors(n=10))

## plot density map
plot(sunfish.dmap,lwd=5,outline=TRUE)

## reset margins to default
par(mar=c(5.1,4.1,4.1,2.1))

Plots a posterior sample of trees

Description

Functions plots a posterior sample of trees, including with mapped discrete characters.

make.transparent is used internally and converts a color to transparent with a certain user-specified alpha level.

Usage

densityTree(trees, colors="blue", alpha=NULL, method="plotTree", 
   fix.depth=FALSE, use.edge.length=TRUE, compute.consensus=TRUE, 
   use.gradient=FALSE, show.axis=TRUE, ...)
make.transparent(color, alpha)

Arguments

Value

Function creates a plot.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Summarizes a stochastic mapped tree or set of trees

Description

Summarizes the result of one or more stochastic maps.

Usage

describe.simmap(tree, ...)
## S3 method for class 'simmap'
summary(object, ...)
## S3 method for class 'multiSimmap'
summary(object, ...)
## S3 method for class 'describe.simmap'
plot(x, ...)

Arguments

Value

An object of class "describe.simmap" with the following elements:

if class(tree)="simmap" then the function simply returns the results of countSimmap combined with the states at each node of the tree and a matrix containing the total and relative times spent in each state on the tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Collapse or resolve polytomies in a tree with a character painted on the edges

Description

Collapses or resolves polytomies in special types of phylogenetic trees. (See di2multi and multi2di.)

Usage

## S3 method for class 'simmap'
di2multi(phy, ...)
## S3 method for class 'simmap'
multi2di(phy, ...)
## S3 method for class 'multiSimmap'
di2multi(phy, ...)
## S3 method for class 'multiSimmap'
multi2di(phy, ...)
## S3 method for class 'contMap'
di2multi(phy, ...)
## S3 method for class 'contMap'
multi2di(phy, ...)
## S3 method for class 'densityMap'
di2multi(phy, ...)
## S3 method for class 'densityMap'
multi2di(phy, ...)

Arguments

Details

The method di2multi collapses branches of zero length (or, more specifically, branches with length shorter than tol) to create a polytomy in a tree or set of trees.

The method multi2di resolves polytomies by adding branches of zero length (while preserving the mappings) in a tree or set of trees.

This methods should theoretically behave similarly to di2multi and multi2di from the ape package.

Value

An object of class "simmap", "multiSimmap", "contMap", or "densityMap", depending on the class of phy.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

contMap, densityMap, di2multi, make.simmap, multi2di, read.simmap

Creates a phylogenetic dot plot

Description

Creates a plot in which different sized dots/circles represent different tip values for a quantitative trait.

Usage

dotTree(tree, x, legend=TRUE, method="plotTree", standardize=FALSE, ...)
dot.legend(x, y, min, max, Ntip, length=5, prompt=FALSE, method="plotTree", 
   ...)

Arguments

Value

Function creates a plot.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Examples

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)

## log-transform trait data
log.mammal<-log(mammal.data)

## plot dotTree
dotTree(mammal.tree,log.mammal,fsize=0.7,
    standardize=TRUE,length=10)

## reset margins to default
par(mar=c(5.1,4.1,4.1,2.1))

Drop a clade from a tree

Description

Internal function for posterior.evolrate.

Usage

drop.clade(tree, tip)

Arguments

Details

Function drops the clade containing the species in tip.

Probably should not use unless you know what you're doing.

Value

An object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Drop all the leaves (tips) from a tree

Description

Drops all the leaves from a tree, leaving behind only the structure leading to internal nodes.

Usage

drop.leaves(tree, ...)

Arguments

Value

An object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Drop tip or tips from an object of class "contMap" or "densityMap"

Description

Drops one or multiple tips from an object of class "contMap" or "densityMap".

Usage

## S3 method for class 'contMap'
drop.tip(phy, tip, ...)
## S3 method for class 'densityMap'
drop.tip(phy, tip, ...)
## S3 method for class 'contMap'
keep.tip(phy, tip, ...)
## S3 method for class 'densityMap'
keep.tip(phy, tip, ...)

Arguments

Details

These functions are equivalent to drop.tip and keep.tip in the ape package, but for objects of class "contMap" and "densityMap".

For more information about objects of class "contMap" or "densityMap", please refer to the documentation pages for contMap or densityMap, respectively.

Value

An object of class "contMap" or "densityMap".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

contMap, densityMap, drop.tip, drop.tip.simmap, keep.tip

Drop or keep tip or tips from an object of class "multiSimmap"

Description

This function drops or keeps one or multiple tips from all the trees of an object of class "multiSimmap".

Usage

## S3 method for class 'multiSimmap'
drop.tip(phy, tip, ...)
## S3 method for class 'multiSimmap'
keep.tip(phy, tip, ...)

Arguments

Details

Equivalent to drop.tip and keep.tip in ape.

This function merely wraps drop.tip.simmap.

Value

An object of class "multiSimmap".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

drop.tip, drop.tip.multiPhylo, drop.tip.simmap, keep.tip

Drop tips or extract clade from tree with mapped discrete character

Description

This function drops one or multiple tips from an object of class "simmap".

Usage

## S3 method for class 'simmap'
drop.tip(phy, tip, ...)
## S3 method for class 'simmap'
keep.tip(phy, tip, ...)
extract.clade.simmap(tree, node)

Arguments

Details

Equivalent to drop.tip and keep.tip but for a tree with a mapped discrete character.

extract.clade.simmap is functionally equivalent to extract.clade but preserves discrete character mappings on the tree.

Following drop.tip in ape, the returned tree is always in "cladewise" order.

Value

A modified object of class "phylo" containing the elements maps and $mapped.edge with the time spent in each state along each edge of the tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

drop.tip, extract.clade, keep.tip, make.simmap, read.simmap, sim.history

Map continuous trait evolution on the tree

Description

Maps a discrete character onto the edges of the tree using variable edge widths.

Usage

edge.widthMap(tree, x, ...)
## S3 method for class 'edge.widthMap'
plot(x, max.width=0.9, legend="trait value", ...)

Arguments

Value

edge.widthMap returns an object of class "edge.widthMap".

plot.edge.widthMap can be used to plot this object.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

contMap, fastAnc

Examples

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)

## extract character of interest
ln.bodyMass<-log(setNames(mammal.data$bodyMass,
    rownames(mammal.data)))

## create "edge.widthMap" object
mammal.ewMap<-edge.widthMap(mammal.tree,ln.bodyMass,
    min.width=0.05)

## plot it
plot(mammal.ewMap,legend="log(body mass)",
    color=palette()[4])

## reset margins to default
par(mar=c(5.1,4.1,4.1,2.1))

Compute the relative frequencies of state changes along edges

Description

Computes the relative frequencies of character state changes along edges from a sample of stochastically mapped character histories.

Usage

edgeProbs(trees)

Arguments

Details

The function assumes that all trees in the sample differ only in their mapped histories & not at all in topology or branch lengths.

Note that edgeProbs only asks whether the starting and ending states of the edge differ in a particular way, and thus ignores multiple-hits along a single edge.

Value

The object that is returned is a matrix with the state changes & the relative frequency of each state change. Rows are in the order of the matrix edge for any of the mapped trees.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

plotSimmap

Estimate diversity at each node of the tree

Description

Estimates the lineage density at each node in the tree based on a biogeographic model (similar to Mahler et al. 2010).

Usage

estDiversity(tree, x, method=c("asr","simulation"), model="ER", ...)

Arguments

Details

Two different methods are implemented in the current version.

For method="asr" the state at the current node, and at each position along each co-extant internal edge, is computed as the marginal (empirical Bayesian) ancestral state reconstruction using the re-rooting method of Yang (2006). The lineage density is then computed as the sum of the marginal reconstructions (posterior probabilities) times the summed marginal ancestral reconstructions across co-extant edges.

For method="simulation", stochastic character mapping is used to generate optional argument nsim stochastic maps of ancestral biogeography. Then the lineage density at each node is computed as the number of co-existing lineages with the same biogeography as the focal node, averaged across stochastic maps.

The importance of this distinction may depend on the degree to which reconstructions at internal nodes are independent, which relates to the distinction between marginal and joint reconstruction (e.g., see Yang 2006).

Value

A vector containing the estimated lineage density at each node

Author(s)

Liam Revell liam.revell@umb.edu

References

Mahler, D. L, L. J. Revell, R. E. Glor, and J. B. Losos. (2010) Ecological opportunity and the rate of morphological evolution in the diversification of Greater Antillean anoles. Evolution, 64, 2731-2745.

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

Yang, Z. (2006) Computational Molecular Evolution. Oxford University Press.

See Also

fitDiversityModel

Bayesian MCMC method for identifying exceptional phenotypic diversification in a phylogeny

Description

Estimates the phylogenetic location of a single rate shift on the tree using Bayesian MCMC (as described in Revell et al., 2012b).

Usage

evol.rate.mcmc(tree, x, ngen=10000, control=list(), ...)
## S3 method for class 'evol.rate.mcmc'
print(x, ...)
## S3 method for class 'evol.rate.mcmc'
summary(object, ...)
## S3 method for class 'summary.evol.rate.mcmc'
print(x, ...)
## S3 method for class 'summary.evol.rate.mcmc'
plot(x, ...)

Arguments

Details

This function takes a phylogenetic tree and data for a single continuously valued character and uses a Bayesian MCMC approach to identify the phylogenetic location of a shift in the evolutionary rate through time.

Default values of control are given in Revell et al. (2012b).

Value

An object of class "evol.rate.mcmc" consisting of at least the following elements:

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Revell, L. J., D. L. Mahler, P. Peres-Neto, and B. D. Redelings (2012) A new method for identifying exceptional phenotypic diversification. Evolution, 66, 135-146.

See Also

anc.Bayes, brownie.lite, evol.vcv, minSplit, posterior.evolrate

Likelihood test for variation in the evolutionary variance-covariance matrix

Description

Fits a multi-regime multivariate Brownian motion model following Revell & Collar (2009).

Usage

evol.vcv(tree, X, maxit=2000, vars=FALSE, ...)

Arguments

Details

The function takes an object of class "simmap" with a mapped binary or multi-state trait and data for an arbitrary number of continuously valued character. It then fits the multiple evolutionary variance-covariance matrix (rate matrix) model of Revell & Collar (2009; Evolution).

evol.vcv performs optimization by maximizing the likelihood with respect to the Cholesky matrices using optim. Optimization is by method="Nelder-Mead". Using box constraints does not make sense here as they would be applied to the Cholesky matrix rather than the target parameters. Users may have to increase maxit for large trees and/or more than two traits.

Value

An object of class "evol.vcv" with the following elements:

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Revell, L. J., and D. C. Collar (2009) Phylogenetic analysis of the evolutionary correlation using likelihood. Evolution, 63, 1090-1100.

See Also

evol.rate.mcmc, brownie.lite

Examples

## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## fit multi-correlation model
sunfish.fit<-evol.vcv(sunfish.tree,sunfish.data[,2:3])
print(sunfish.fit)

Likelihood test for a shift in the evolutionary correlation between traits

Description

Fits a multi-regime model for differences in the evolutionary variance-covariance structure or correlation between two continuous traits, following Revell & Collar (2009) and Revell et al. (2022).

Usage

evolvcv.lite(tree, X, maxit=2000, tol=1e-10, ...)

Arguments

Details

This function takes an object of class "simmap" with a mapped binary or multi-state trait and data for two and only two continuously valued character. It then fits (by default) four different evolutionary models: common rates and correlation; different rates, common correlation; different correlations, common rates; no common structure.

In addition to the four default models specified above, evolvcv.lite now fits an additional four additional models.

The set of models to be fit can be specified using the optional argument models in multiple ways.

First, if left unspecified, then the four models listed above will be fit.

Second, if models is set to "all models" than eight models will be fit.

Lastly, one or more (up to all eight) models can be fit by encoding the models to be fit into a single vector containing a subset or all of the following elements: "1", "2", "2b", "3", "3b", "3c", and "4". These codes correspond to the following eight models: 1. common rates, common correlation; 2. different rates, common correlation; 2b. different rates for trait 1 only, common correlation; 2c. different rates for trait 2 only, common correlation; 3. common rates, different correlations; 3b. different rates for trait 1 only, different correlations; 3c. different rates for trait 2 only, different correlation; and 4. no common structure.

Value

A list with the results summarized for each model.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Revell, L. J., and D. C. Collar (2009) Phylogenetic analysis of the evolutionary correlation using likelihood. Evolution, 63, 1090-1100.

Revell, L. J., K. S. Toyama, and D. L. Mahler (2022) A simple hierarchical model for heterogeneity in the evolutionary correlation on a phylogenetic tree. PeerJ, 10, e13910.

See Also

brownie.lite, evol.vcv

Examples

## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## fit hierarchical common-structure models
sunfish.fit<-evolvcv.lite(sunfish.tree,
    sunfish.data[,2:3],models="all models")

## print fitted models
print(sunfish.fit)

## compare models
anova(sunfish.fit)

Exhaustive and branch & bound MP optimization

Description

This function does exhaustive and branch & bound MP searches.

Usage

exhaustiveMP(data, tree=NULL, method="branch.and.bound")

Arguments

Details

Should probably not be used for more than about 8 species (and definitely not more than 10 species). Performs parsimony calculations using parsimony in the phangorn package (Schliep, 2011).

Value

A "phylo" or "multiPhylo" object that is the MP tree or set of MP trees. It also returns the parsimony scores in attr(trees,"pscore") or attr(trees[[i]],"pscore") for the ith tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (2004) Inferring Phylogenies. Sinauer.

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

Schliep, K. P. (2011) phangorn: phylogenetic analysis in R. Bioinformatics, 27, 592-593.

See Also

mrp.supertree, optim.parsimony, pratchet

Expands (or contracts) the tip-spacing of a given clade or clades

Description

Modify the tip-spacing of a plotted tree.

Usage

expand.clade(tree, node, factor=5)
## S3 method for class 'expand.clade'
plot(x, ...)

Arguments

Details

The purpose of this function is to compute a custom tip-spacing for users who want to expand or contract the tip-spacing of the descendant taxa from a given node or nodes.

Value

The function returns an object of class "expand.clade" which consists of the (possibly re-ordered) tree and a numerical vector with the calculated tip spacing based on the expansion factor specified by the user.

This object can be plotted using the S3 plot method for the object class; or it can be plotted simply by calling a standard plotting function on the tree & tip spacings.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Export trees & data in XML format

Description

Exports trees & character data in XML format.

Usage

export.as.xml(file, trees, X)

Arguments

Details

Can be used to create input file for the program SIMMAP v1.5 (Bollback 2006).

Value

A file.

Author(s)

Liam Revell liam.revell@umb.edu

References

Bollback, J. P. (2006) Stochastic character mapping of discrete traits on phylogenies. BMC Bioinformatics, 7, 88.

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

See Also

make.simmap, read.nexus, read.simmap, write.simmap

Plots special types of phylogenetic trees

Description

Plots phylogenies (or phylogenetic trees and comparative data) in a variety of different styles.

Usage

fancyTree(tree, type=c("extinction","traitgram3d","droptip","densitymap",
   "contmap","phenogram95","scattergram"), ..., control=list())
phyloScattergram(tree, X=NULL, ...)
phenogram95(tree, x=NULL, ...)

Arguments

Details

This function plots a phylogeny or phylogenetic tree and comparative data in a variety of different styles, depending on the value of type. In some instances, fancyTree is now just a wrapper for other phytools functions, such as contMap and densityMap.

If type="extinction" (or any unambiguous abbreviation) the function will plot a tree in which branches preceding the MRCA of all extant taxa and branches leading only to extinct lineages are plotted with dashed red lines.

If type="traitgram3d" the function will plot a three dimensional traitgram (that is, a projection of the tree into three dimensional morphospace where two dimensions are the phenotypic trait and the third axis is time since the root). In this case, the additional argument X, a matrix containing the tip values of all species (with species IDs as row names) should be supplied. Optionally, the user can also supply the matrix A, which contains the ancestral states in the tree with rows labeled by node number.

If type="droptip" the function will create a two panel figure in which the first panel is the tree with lineages to be pruned highlighted; and the second panel is the pruned tree. In this case, the additional argument tip, the tip name or vector of tip names to be dropped, must be supplied.

If type="densitymap", a posterior probability density "heat-map" is created based on a set of trees in a "multiSimmap" object containing a binary [0,1] mapped character. (See densityMap for additional optional arguments if type="densitymap".)

If type="contmap", reconstructed continuous trait evolution is mapped on the tree. Again, see contMap for additional arguments if type="contmap".

If type="phenogram95" a 95% traitgram (aka. "phenogram") is plotted using transparency to visualize uncertainty at ancestral nodes and along branches. Most of the options of phenogram are available.

Finally, if type="scattergram" a phylogenetic scatter plot matrix containing contMap style trees on the diagonal and phylomorphospace plots in non-diagonal panels is produced. For this type a trait matrix X must also be supplied. The only additional arguments available for this type are ftype, fsize, colors, and label. (See phylomorphospace for details on how these arguments should be used.) This function calls phyloScattergram (which is also now exported to the name space) internally. In addition to creating a plot, phyloScattergram also returns an object of class "phyloScattergram" which can be replotted using different options if desired.

Presently only type="traitgram3d" uses the list control which can be supplied the same set of control parameters as phylomorphospace3d, as well as the control parameter maxit which will be passed to anc.ML.

Finally, the optional argument hold will be passed to multiple methods if supplied. It is a logical value that indicates whether or not the output to the graphical device should be held using dev.hold before plotting (defaults to hold=TRUE).

Value

This function plots different types of phylogenetic trees. For type="droptip" the function also returns the pruned tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

Evans, M. E. K., Smith, S. A., Flynn, R. S., Donoghue, M. J. (2009) Climate, niche evolution, and diversification of the "bird-cage" evening primroses (Oenothera, sections Anogra and Kleinia). American Naturalist, 173, 225-240.

Revell, L. J. (2013) Two new graphical methods for mapping trait evolution on phylogenies. Methods in Ecology and Evolution, 4, 754-759.

Revell, L. J. (2014) Graphical methods for visualizing comparative data on phylogenies. Chapter 4 in Modern phylogenetic comparative methods and their application in evolutionary biology: Concepts and practice (L. Z. Garamszegi ed.), pp. 77-103.

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

See Also

contMap, densityMap, drop.tip, phenogram, phylomorphospace3d, plot.phylo, plotSimmap

Examples

## plot tree with extinction
set.seed(10)
tree<-pbtree(b=1,d=0.4,t=4)
fancyTree(tree,type="extinction")

## Not run: 
## plot 3D traitgram
## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)
fancyTree(sunfish.tree,type="traitgram3d",
    X=sunfish.data[,2:3],
    control=list(spin=FALSE))
## End(Not run)
	
## plot with dropped tips
tree<-pbtree(n=30)
tips<-sample(tree$tip.label)[1:10]
pruned<-fancyTree(tree,type="droptip",tip=tips)

## reset par to default
par(mfrow=c(1,1),mar=c(5.1,4.1,4.1,2.1))

## Not run: 
## plot 95-percent CI phenogram
data(mammal.tree)
data(mammal.data)
bodyMass<-setNames(mammal.data$bodyMass,
    rownames(mammal.data))
fancyTree(mammal.tree,type="phenogram95",x=bodyMass,
    fsize=0.7,ftype="i")
## End(Not run)

## reset mar to defaults
par(mar=c(5.1,4.1,4.1,2.1))

(Reasonably) fast estimation of ML ancestral states

Description

Estimates ancestral states for a continuous character under maximum likelihood.

Usage

fastAnc(tree, x, vars=FALSE, CI=FALSE, ...)

Arguments

Details

This function performs (reasonably) fast estimation of the ML ancestral states for a continuous trait by taking advantage of the fact that the state computed for the root node of the tree during Felsenstein's (1985) contrasts algorithm is also the MLE of the root node. Thus, the function re-roots the tree at all internal nodes and computes the contrasts state at the root each time.

The function can also (optionally) compute variances or 95% confidence intervals on the estimates.

Value

An object of class "fastAnc" consisting of either: a named vector containing the states at internal nodes - names are node numbers; or a list containing ancestral state estimates (ace), variances on the estimates (var), and/or 95% confidence intervals (CI95).

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

ace, anc.Bayes, anc.ML, ancr pic

Examples

## load data from Garland et al. (1992)
data(mammal.tree)
data(mammal.data)

## extract character of interest
ln.bodyMass<-log(setNames(mammal.data$bodyMass,
    rownames(mammal.data)))

## estimate ancestral body sizes
fit.BM<-fastAnc(mammal.tree,ln.bodyMass,CI=TRUE)
print(fit.BM,printlen=10)

(Reasonably) fast quantitative trait simulation on phylogenies

Description

Simulates one or multiple continuous traits on the tree under various evolutionary models.

Usage

fastBM(tree, a=0, mu=0, sig2=1, bounds=c(-Inf,Inf), internal=FALSE, nsim=1, 
   ...)

Arguments

Details

This function conducts (reasonably) fast quantitative trait simulation on a phylogeny under several different models: Brownian motion (default), BM with a trend (for mu!=0), bounds (for bounds!=c(-Inf, Inf)), and OU.

Value

A vector (for nsim=1) or matrix containing the tip states for the n species in the tree, and (optionally) the ancestral states for internal nodes.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

sim.corrs

Examples

## load example tree
data(anoletree)

## simulate 10 characters on the Anolis tree 
## under Brownian motion
X<-fastBM(anoletree,nsim=10)
head(X)

## create a plot
phylo.heatmap(anoletree,X,fsize=c(0.4,0.8,0.8),
    standardize=TRUE,colors=terrain.colors(n=20))

Get the MRCA (or height above the root of the MRCA) of a pair of tip taxa

Description

Finds the most recent common ancestor (MRCA) for a pair of tip taxa.

Usage

fastMRCA(tree, sp1, sp2)
fastHeight(tree, sp1, sp2)
fastDist(tree, sp1, sp2)

Arguments

Details

Function (fastMRCA) returns the most recent common ancestor (node number) for a pair of taxa; or, in the case of fastHeight, the height above the root of the MRCA of a pair of taxa; or, in the case of fastDist, the patristic distance between a pair of taxa.

This function is mostly redundant with findMRCA (or findMRCA(...,type="height") in the case of fastHeight), but for very large trees will be considerably faster.

(Also see getMRCA in the ape package.)

Value

The node number of the MRCA, the height above the root (for fastHeight), or the patristic distance between two taxa (for fastDist).

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

getMRCA, findMRCA, mrca

Examples

## simulate 2000-tip tree
tree<-pbtree(n=2000)

## find the MRCA of two randomly chosen tips
tips<-sample(tree$tip.label,2)
anc<-fastMRCA(tree,tips[1],tips[2])

Get the MRCA of a set of taxa

Description

Finds the most recent common ancestor (MRCA) of a set of tips.

Usage

findMRCA(tree, tips=NULL, type=c("node","height"))

Arguments

Details

This function returns node number of the most recent common ancestor of a set of taxa.

If tips==NULL and type="node" (the default) it will return the result of a normal function call to mrca.

If tips=NULL and type="height" it will return a matrix equal to that produced by vcv.phylo.

From phytools 0.5-66 forward, findMRCA uses getMRCA in the ape package internally, which results in a big speed-up. Even though the two functions are thus totally redundant I have left findMRCA in the package namespace to ensure backward compatibility.

Value

The node number of the MRCA, or a matrix of node numbers (if tips==NULL) - for type="node"; or the height of the MRCA, or a matrix of heights (if tips==NULL) - for type="height".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

findMRCA, mrca

Examples

## load tree
data(anoletree)

## find the common ancestor of three taxa
anc<-findMRCA(anoletree,c("cristatellus","cooki",
    "gundlachi"))

## graph the tree
plotTree(anoletree,type="fan",fsize=0.7,lwd=1)

## label the identified ancestor
nodelabels(node=anc,frame="circle",pch=21,cex=1.5,
    bg="blue")
legend("topleft",
    "most recent common ancestor\nof Puerto Rican TG anoles",
    pch=21,pt.cex=1.5,pt.bg="blue",cex=0.7,bty="n")
  
## reset margin to default
par(mar=c(5.1,4.1,4.1,2.1)) 

Fits birth-death (speciation/extinction) model to reconstructed phylogeny

Description

Fits a birth-death (fit.bd) or pure-birth (fit.yule) model to a reconstructed phylogenetic tree with branch lengths.

Usage

fit.bd(tree, b=NULL, d=NULL, rho=1, ...)
fit.yule(tree, b=NULL, d=NULL, rho=1, ...)
lik.bd(theta, t, rho=1, N=NULL)
## S3 method for class 'fit.bd'
print(x, ...)

Arguments

Details

The function fit.bd fits a birth-death model to a phylogenetic tree with edge lengths and a (potentially) incomplete sampling fraction.

The function fit.yule fits a pure-birth model with a (potentially) incomplete sampling fraction.

The function lik.bd computes the likelihood of a set of birth & death rates given the set of branching times computed for a tree and a sampling fraction.

Value

fit.bd returns an object of class "fit.bd" which can be printed. This object is a list containing the fitted model parameters, likelihood, optimization conditions, a summary of the optimization, and a likelihood function.

fit.yule returns an object of class "fit.yule". This object is a list containing the fitted model parameter, likelihood, optimization conditions, a summary of the optimization, and a likelihood function.

Author(s)

Liam Revell liam.revell@umb.edu

References

Nee, S., May, R. M. and Harvey, P. H. (1994) The reconstructed evolutionary process. Philosophical Transactions of the Royal Society of London B, 344, 305-311.

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

Stadler, T. (2012) How can we improve the accuracy of macroevolutionary rate estimates? Systematic Biology, 62, 321-329.

See Also

birthdeath

Examples

## load tree
data(salamanders)

## compute sampling fraction based on 55 species of Plethodon
sampling.f<-Ntip(salamanders)/55

## fit birth-death model
bd.fit<-fit.bd(salamanders,rho=sampling.f)
print(bd.fit)

## fit Yule model
yule.fit<-fit.yule(salamanders,rho=sampling.f)
print(yule.fit)

## compare b-d and yule models
anova(yule.fit,bd.fit)

## create a likelihood surface for b-d model
ngrid<-100
b<-seq(0.01,0.06,length.out=ngrid)
d<-seq(0.005,0.03,length.out=ngrid)
logL<-sapply(d,function(d,b) sapply(b,function(b,d) 
    bd.fit$lik(c(b,d)),d=d),b=b)
contour(x=b,y=d,logL,nlevels=100,
    xlab=expression(lambda),
    ylab=expression(mu),bty="l")
title(main="Likelihood surface for plethodontid diversification",
    font.main=3)
points(bd.fit$b,bd.fit$d,cex=1.5,pch=4,
    col="blue",lwd=2)
legend("bottomright","ML solution",pch=4,col="blue",
    bg="white",pt.cex=1.5,pt.lwd=2)

Evolutionary model fitting with intraspecific variability using Bayesian MCMC

Description

fitBayes uses Bayesian MCMC to sample terminal states (species means) as well as the parameters of an evolutionary model from their joint posterior distribution, following Revell & Reynolds (2012).

Usage

fitBayes(tree, x, ngen=10000, model="BM", method="reduced", control=list())

Arguments

Value

An object of class "fitBayes" that includes a matrix (mcmc) with a number of rows ngen/control$sample+1 containing the posterior sample and likelihoods.

Matrix columns are labeled by species (for species means and variances), or by the corresponding evolutionary parameter.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Revell, L. J. and R. G. Reynolds. (2012) A new Bayesian method for fitting evolutionary models to comparative data with intraspecific variation. Evolution, 66, 2697-2707.

See Also

anc.Bayes, brownie.lite, evol.rate.mcmc

Fit diversity-dependent phenotypic evolution model

Description

Fits a diversity-dependent phenotypic evolution model (similar to Mahler et al. 2010).

Usage

fitDiversityModel(tree, x, d=NULL, showTree=TRUE, tol=1e-6)
## S3 method for class 'fitDiversityModel'
logLik(object, ...)
## S3 method for class 'fitDiversityModel'
print(x, ...)

Arguments

Value

An object of class "fitDiversityModel" consisting of the following elements:

Author(s)

Liam Revell liam.revell@umb.edu

References

Mahler, D. L, L. J. Revell, R. E. Glor, and J. B. Losos (2010) Ecological opportunity and the rate of morphological evolution in the diversification of Greater Antillean anoles. Evolution, 64, 2731-2745.

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

See Also

brownie.lite, estDiversity, evol.rate.mcmc

Fits extended Mk model for discrete character evolution

Description

The functions fitMk, fitmultiMk, fitpolyMk, fitHRM, fitMk.parallel, fitgammaMk, fitfnMk, and mcmcMk fit various flavors of the extended Mk model (Lewis, 2001) for discrete character evolution on a reconstructed phylogeny.

Usage

fitMk(tree, x, model="SYM", fixedQ=NULL, ...)
## S3 method for class 'fitMk'
plot(x, ...)
## S3 method for class 'gfit'
plot(x, ...)
fitmultiMk(tree, x, model="ER", ...)
fitpolyMk(tree, x, model="SYM", ordered=FALSE, ...)
graph.polyMk(k=2, model="SYM", ordered=FALSE, ...)
## S3 method for class 'fitpolyMk'
plot(x, ...)
mcmcMk(tree, x, model="ER", ngen=10000, ...)
## S3 method for class 'mcmcMk'
plot(x, ...)
## S3 method for class 'mcmcMk'
density(x, ...)
## S3 method for class 'density.mcmcMk'
plot(x, ...)
fitHRM(tree, x, model="ARD", ncat=2, ...)
## S3 method for class 'fitHRM'
plot(x, ...)
fitMk.parallel(tree, x, model="SYM", ncores=1, ...)
fitgammaMk(tree, x, model="ER", fixedQ=NULL, nrates=8, ...)
fitfnMk(tree, x, model="polynomial", degree=2, ...)

Arguments

Details

The function fitMk fits a so-called extended Mk model for discrete character evolution (Lewis, 2001).

plot.fitMk plots an object of class "fitMk" returned by fitMk. plot.gfit plots an object of class "gfit" from geiger's fitDiscrete function. Both plots portray the fitted model using a graph of arrows connecting states.

The function fitmultiMk fits an Mk model in which the transition rates between character states are allowed to vary depending on the mapped state of a discrete character on the tree following Revell et al. (2024). It can be combined with, for example, paintSubTree to test hypotheses about how the process of discrete character evolution for x varies between different parts of the tree.

The function fitgammaMk fits an Mk model in which the edge rates are assumed to have been sampled randomly from a \Gamma distribution with mean of 1.0 and shape parameter \alpha (Revell and Harmon, In review).

The function fitfnMk fit an ordered Mk model in which the backward and forward transition rates between adjacent levels of the trait vary according to a functional form. Presently that function form is an nth degree polynomial, in which degree is set by the user (but defaults to degree = 2).

The function fitpolyMk fits an Mk model to data for a discrete character with intraspecific polymorphism. Polymorphic species should be coded with the name of the two or more states recorded for the species separated by a plus sign + (e.g., A+B would indicate that both states A and B are found in the corresponding taxon). Invariably it's assumed that transitions between states must occur through a polymorphic condition, whereas transitions cannot occur directly between two incompatible polymorphic conditions. For instance, a transition between A+B and B+C would have to occur through the monomorphic state B. At time of writing, this function permits the models "ER" (equal rates for all permitted transitions), "SYM" (symmetric backward & forward rates for all permitted transitions), "ARD" (all-rates-different for permitted transitions), and a new model called "transient" in which the acquisition of polymorphism (e.g., A -> A+B) is assumed to occur at a different rate than its loss (e.g., A+B -> B). The method plot.fitpolyMk plots the fitted Mk model with intraspecific polymorphism.

The function mcmcMk runs a Bayesian MCMC version of fitMk. The shape of the prior distribution of the transition rates is \Gamma, with \alpha and \beta via the argument prior, which takes the form of a list. The default value of \alpha is 0.1, and \beta defaults to a value such that \alpha/\beta is equal to the parsimony score for x divided by the sum of the edge lengths of the tree. The shape of the proposal distribution is normal, with mean zero and a variance that can be controlled by the user via the optional argument prior.var. The argument auto.tune, if TRUE or FALSE, indicates whether or not to 'tune' the proposal variance up or down to target a particular acceptance rate (defaults to 0.5). auto.tune can also be a numeric value between 0 and 1, in which case this value will be the target acceptance ratio. The argument plot indicates whether the progress of the MCMC should be plotted (defaults to TRUE, but runs much faster when set to FALSE).

The method plot.mcmcMk plots a log-likelihood trace and a trace of the rate parameters from the MCMC. (This the same graph that is created by setting plot=TRUE in mcmcMk.) The method density.mcmcMk computes a posterior density on the transition rates in the model from the posterior sample obtained in the MCMC, will import the package coda if it is available, and returns an object of class "density.mcmcMk". Finally, the method plot.density.mcmcMk creates a plot of the posterior density (or a set of plots) for the transition rates between states.

Finally, the function fitHRM fits a hidden-rate Mk model following Beaulieu et al. (2013). For the hidden-rate model we need to specify a number of rate categories for each level of the trait - and this can be a vector of different values for each trait. We can also choose a model ("ER", "SYM", or "ARD"), as well as whether or not to treat the character as a 'threshold' trait (umbral=TRUE, defaults to FALSE). This latter model is basically one that allows absorbing conditions for some hidden states. Since this can be a difficult optimization problem, the optional argument niter sets the number of optimization iterations to be run. niter defaults to niter=10. To fit the same default hidden-rates model as is implemented in corHMM, one should set corHMM_model=TRUE and ordered_hrm=FALSE.

Note that (by default) both fitMk and fitmultiMk recycle code from ace in the ape package for computing the likelihood. (If the optional argument lik.func="pruning" then alternative, slightly faster, phytools code for the pruning algorithm is used.) fitpolyMk, mcmcMk, and fitHRM use fitMk internally to compute the likelihood.

Value

An object of class "fitMk", "fitmultiMk", "fitpolyMk", "mcmcMk", "fitHRM", "fitgammaMk", or "fitfnMk". In the case of density.mcmcMk an object of class "density.mcmcMk".

plot.fitMk, plot.gfit, and plot.HRM invisibly return the coordinates of vertices of the plotted Q-matrix.

Author(s)

Liam Revell liam.revell@umb.edu

References

Beaulieu, J. M., B. C. O'Meara, and M. J. Donoghue (2013) Identifying hidden rate changes in the evolution of a binary morphological character: The evolution of plant habit in campanulid angiosperms. Systematic Biology, 62, 725-737.

FitzJohn, R. G., W. P. Maddison, and S. P. Otto (2009) Estimating trait-dependent speciation and extinction rates from incompletely resolved phylogenies. Systematic Biology, 58, 595-611.

Lewis, P. O. (2001) A likelihood approach to estimating phylogeny from discrete morphological character data. Systematic Biology, 50, 913-925.

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

Revell, L. J. and L. J. Harmon (2022) Phylogenetic Comparative Methods in R. Princeton University Press.

Revell, L. J. and L. J. Harmon. In review. A discrete character evolution model for phylogenetic comparative biology with \Gamma-distributed rate heterogeneity among branches of the tree.

Revell, L. J., K. P. Schliep, D. L. Mahler, and T. Ingram (2024) Testing for heterogeneous rates of discrete character evolution on phylogenies. Journal of Evolutionary Biology, 37, 1591-1602.

See Also

ace, make.simmap, simmap

Examples

## load tree and data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract discrete character (feeding mode)
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))

## fit "ER" model
fit.ER<-fitMk(sunfish.tree,fmode,model="ER")
print(fit.ER)

## fit "ARD" model
fit.ARD<-fitMk(sunfish.tree,fmode,model="ARD")
print(fit.ARD)

## compare the models
AIC(fit.ER,fit.ARD)

## load tree and data from Benitez-Alvarez et al. (2000)
data(flatworm.data)
data(flatworm.tree)

## extract discrete character (habitat)
habitat<-setNames(flatworm.data$Habitat,
    rownames(flatworm.data))

## fit polymorphic models "ER" and "transient"
fitpoly.ER<-fitpolyMk(flatworm.tree,habitat,
    model="ER")
fitpoly.transient<-fitpolyMk(flatworm.tree,habitat,
    model="transient")

## print fitted models
print(fitpoly.ER)
print(fitpoly.transient)

## compare model
AIC(fitpoly.ER,fitpoly.transient)

## plot models
par(mfrow=c(2,1))
plot(fitpoly.ER)
mtext("a) ER polymorphic model",adj=0,line=1)
plot(fitpoly.transient)
mtext("b) Transient polymorphic model",adj=0,
     line=1)

## reset par to default
par(mfrow=c(1,1))

Function to test for correlated evolution of binary traits

Description

Fits Pagel's (1994) model for the correlated evolution of two binary characters.

Usage

fitPagel(tree, x, y, method="fitMk", model="ARD", dep.var="xy", ...)
## S3 method for class 'fitPagel'
plot(x, ...)

Arguments

Details

fitPagel fits both an independent evolution model, as well as Pagel's (1994) binary dependent model, and compares them with a likelihood-ratio test.

plot.fitPagel plots the fitted models using arrows.

Value

An object of class "fitPagel" which contains the optimized matrices under an independence & a dependence model, log-likelihoods, a likelihood ratio, and a P-value for the independence model based on a chi-squared test.

plot.fitPagel creates a plot showing the different fitted models with arrows.

Author(s)

Liam Revell liam.revell@umb.edu

References

Pagel, M. (1994) Detecting correlated evolution on phylogenies: A general method for the comparative analysis of discrete characters. Proceedings of the Royal Society B, 255, 37-45.

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

See Also

ace, fitMk, make.simmap

Examples

## Not run: 
## load data
data(bonyfish.tree)
data(bonyfish.data)

## extract discrete characters
spawning_mode<-setNames(bonyfish.data$spawning_mode,
    rownames(bonyfish.data))
paternal_care<-setNames(bonyfish.data$paternal_care,
    rownames(bonyfish.data))

## fit correlational model
bonyfish.pagel<-fitPagel(bonyfish.tree,paternal_care,
    spawning_mode)

## test for a difference between models
anova(bonyfish.pagel)

## plot fitted models
plot(bonyfish.pagel,lwd.by.rate=TRUE)

## reset par
par(mar=c(5.1,4.1,4.1,2.1),mfrow=c(1,1))
## End(Not run)

Fits multi-state threshold model using the discrete approximation

Description

This function uses the discrete approximation of Boucher and Demery (2016) to fit a multi-state discrete character threshold model following Felsenstein (2012; Revell 2014).

Usage

fitThresh(tree, x, sequence=NULL, ...)

Arguments

Value

An object of class "fitThresh".

Author(s)

Liam Revell liam.revell@umb.edu

References

Boucher, F. C., and V. Demery (2016) Inferring bounded evolution in phenotypic characters from phylogenetic comparative data. Systematic Biology, 65, 651-661.

Felsenstein, J. (2012) A comparative method for both discrete and continuous characters using the threshold model. American Naturalist, 179, 145-156.

Revell, L. J. (2014) Ancestral character estimation under the threshold model from quantitative genetics. Evolution, 68, 743-759.

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

See Also

ancThresh, bounded_bm, fitmultiBM, threshBayes

Examples

## Not run: 
## load data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract character of interest
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))

## fit model
sunfish_thresh<-fitThresh(sunfish.tree,fmode,
    levs=100)
sunfish_thresh

## fit ARD model for comparison
sunfish_ard<-fitMk(sunfish.tree,fmode,model="ARD")
sunfish_ard

## compare results
anova(sunfish_thresh,sunfish_ard)

## estimate ancestral states under threshold model
anc_sunfish<-ancr(sunfish_thresh)

## plot results
plot(anc_sunfish,mar=c(0.1,0.1,4.1,0.1),
    args.plotTree=list(lwd=2,type="cladogram",
        nodes="inner",offset=1),
    args.nodelabels=list(piecol=hcl.colors(n=2),
        cex=0.6),
    args.tiplabels=list(cex=0.5),legend=FALSE)
legend("topleft",c("non-piscivorous","piscivorous"),
    pch=16,col=hcl.colors(n=2),pt.cex=2,bty="n")
	
## reset par to defaults
par(mar=c(5.1,4.1,4.1,2.1),cex.axis=1)
## End(Not run)

Fits multi-rate discrete character dependent continuous trait evolution

Description

Fits a multi-rate discrete-state-dependent Brownian motion model using the discrete approximation of Boucher & Demery (2016).

Usage

fitmultiBM(tree, x, y=NULL, model="ER", ncat=1, ...)

Arguments

Details

This function uses the discrete approximation of Boucher & Demery (2016) to fit a model in which the rate of Brownian evolution of a continuous trait (in x) depends on the state of a discrete character (in y), where the discrete and continuous character are modeled jointly. If, in fact, the rates of evolution of x depend on the state of y, this will lead to more accurate model parameter estimates than when the discrete and continuous characters are separately modeled.

Optional arguments include parallel (whether to distribute matrix exponentiation across nodes, which defaults to parallel=FALSE), levs (the number of levels for the discrete approximation, which defaults to levs=100), nullmodel (a logical indicating whether or not to fit a null model without state-dependent continuous trait evolution, which defaults to nullmodel=FALSE), and plot_model (a logical indicating whether or not to graph the discretized model prior to fitting, which defaults to plot_model=FALSE).

Value

An object of class "fitmultiBM".

Author(s)

Liam Revell liam.revell@umb.edu

References

Boucher, F. C., and V. Demery (2016) Inferring bounded evolution in phenotypic characters from phylogenetic comparative data. Systematic Biology, 65, 651-661.

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

See Also

bounded_bm, brownie.lite, fitMk

Examples

## Not run: 
## load tree and data
data(eel.tree)
data(eel.data)
feed_mode<-setNames(eel.data$feed_mode,
    rownames(eel.data))
lnTL<-setNames(log(eel.data$Max_TL_cm),
    rownames(eel.data))
	
## fit state-dependent model
eel_sdmodel<-fitmultiBM(eel.tree,lnTL,feed_mode,
    model="ARD",parallel=TRUE,levs=100,
    plot_model=TRUE)

## fit null model
eel_nullmodel<-fitmultiBM(eel.tree,lnTL,feed_mode,
    model="ARD",parallel=TRUE,levs=100,
    null_model=TRUE,plot_model=TRUE)

## fit null model with hidden-rates
eel_nullmodel.hrm<-fitmultiBM(eel.tree,lnTL,feed_mode,
    model="ARD",ncat=2,parallel=TRUE,levs=100,
    null_model=TRUE,plot_model=TRUE)

## fit state-dependent model with hidden-rates
eel_sdmodel.hrm<-fitmultiBM(eel.tree,lnTL,feed_mode,
    model="ARD",ncat=2,parallel=TRUE,levs=100,
    plot_model=TRUE)

## compare models
anova(eel_nullmodel,eel_sdmodel,eel_nullmodel.hrm,
    eel_sdmodel.hrm)
## End(Not run)

Coerces a phylogenetic tree to be ultrametric

Description

Coerces an object of class "phylo" to be ultrametric.

Usage

force.ultrametric(tree, method=c("nnls","extend"), ...)

Arguments

Details

force.ultrametric coerces a non-ultrametric tree to be ultrametric.

This is achieved either by using nnls.tree from the phangorn package to compute the set of edge lengths that result in a minimized sum-of-squares distance between the patristic distance of the output and input trees (method="nnls"); or by simply extending all the external edges of the tree to match the external edge with the greatest total height (method="extend").

Note that neither of these should be treated as formal statistical methods for inferring an ultrametric tree. Rather, this method can be deployed when a genuinely ultrametric tree read from file fails is.ultrametric for reasons of numerical precision.

Value

An ultrametric tree in an object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

is.ultrametric, nnls.tree

Internally used function

Description

Internally used function to compute the likelihood under a \Gamma model.

Usage

gamma_pruning(par, nrates=4, tree, x, model=NULL, median=TRUE,
  expm.method="Higham08.b", ...)

Arguments

Value

A value of the log-likelihood.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

\gamma test of Pybus & Harvey (2000)

Description

Conducts \gamma-test of Pybus & Harvey (2000).

Usage

gammatest(x)

Arguments

Value

A an object of class "gammatest" consisting of a list that contains:

Author(s)

Liam Revell liam.revell@umb.edu

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

ltt, mccr

Examples

## load tree
data(darter.tree)

## run gammatest on "ltt" object
gammatest(ltt(darter.tree,plot=FALSE))

Simulate a DNA alignment on the tree under a model

Description

Simulates DNA sequence on tree under the specified model.

Usage

genSeq(tree, l=1000, Q=NULL, rate=1, format="DNAbin", ...)

Arguments

Details

Uses sim.Mk internally.

Value

An object of class "DNAbin" or "phyDat", or a matrix of nucleotides.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Examples

## load tree
data(mammal.tree)

## rescale edge lengths
mammal.tree$edge.length<-mammal.tree$edge.length/
    max(nodeHeights(mammal.tree))*0.2

## simulate gamma rate heterogeneity
gg<-rgamma(n=100,shape=0.25,rate=0.25)

## simulate DNA sequences with rate heterogeneity
dna<-genSeq(mammal.tree,l=100,rate=gg)

Adds a geological (or other temporal) legend to a plotted tree

Description

Adds a geological legend to a plotted tree.

Usage

geo.legend(leg=NULL, colors=NULL, alpha=0.2, ...)
geo.palette()

Arguments

Details

The function geo.legend adds a geological (or other temporal) legend to a plotted tree.

The function geo.palette returns a geological time color palette to the user.

Value

geo.legend adds a visual element to a plotted tree and invisible returns an object of class geo.legend containing the time periods and colors of the painted legend.

geo.palette simply returns a geological timescale color palette as an object of class "geo.palette".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Examples

## load tree
data(anoletree)

## rescale tree to 50 ma total depth
anoletree<-rescale(anoletree,model="depth",depth=50)

## plot phylogeny
plotTree(anoletree,ylim=c(-0.16,1)*Ntip(anoletree),
    ftype="i",lwd=1,fsize=0.5)

## add geological color legend
obj<-geo.legend()

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1))

Get position or node of a plotted tree interactively

Description

Return the phylogenetic position of a mouse click on a plotted tree.

Usage

get.treepos(message=TRUE, ...)
getnode(...)

Arguments

Details

Both get.treepos and getnode are primarily meant for internal use in other phytools functions.

get.treepos returns the index of the node at the end of the selected edge, along with the branch distance to that node.

getnode simply returns the closest node to the user mouse click.

Value

A list for get.treepos and a node number for getnode.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Get all subtrees larger than or equal to a specified size

Description

This function gets all subtrees that cannot be further subdivided into two reciprocally monophyletic subtrees of size >= clade.size.

Usage

getCladesofSize(tree, clade.size=2)

Arguments

Value

An object of class "multiPhylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

extract.clade, getDescendants

Get descendant node numbers

Description

Returns the descendants or parent of a specified node.

Usage

getDescendants(tree, node, curr=NULL)
getParent(tree, node)

Arguments

Details

getDescendants returns the set of node & tip numbers descended from node.

getParent returns the single parent node of a specified node number (or NULL if node is already the root).

Value

The set of node and tip numbers for the nodes and tips descended from node in a vector, or for getParent the single node preceding node in the tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

Descendants, paintSubTree

Returns a list of the extant or extinct lineages in a tree containing non-contemporaneous tips

Description

Computes the set of extant or extinct tips from a phylogenetic tree.

Usage

getExtant(tree, tol=1e-8)
getExtinct(tree, tol=1e-8)

Arguments

Details

The function getExtant takes a tree as input and returns a vector containing the names of all the tips that have a height above the root that is equal (to a degree of numerical precision determined by tol) to the height of the highest tip. These tips are presumed to be "extant."

getExtinct returns the complement.

Value

A vector with the tip names of extant or extinct species in the tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

nodeHeights

Get the sister node number, label, or set of nodes for a node or tip

Description

Computes the sister taxon or node.

Usage

getSisters(tree, node, mode=c("number","label"))

Arguments

Details

This function takes a tree and node or tip number of label and returns the number or label of the sister or sisters to that node or tip.

Value

If mode="number" this function returns an integer or vector containing the node number of numbers of the sister node or tip. If mode="label" then this function returns a list containing up to two vectors: one for the node numbers of labels of sister nodes (if applicable); and the other containing the tip labels of the sister tips.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

getDescendants, Siblings

Get the states at nodes or tips from a mapped tree

Description

Gets the states from the nodes or tips of a mapped tree (e.g., make.simmap).

Usage

getStates(tree, type=c("nodes","tips","both"))

Arguments

Value

A named vector (for "phylo") or matrix (for "multiPhylo").

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

describe.simmap, make.simmap, read.simmap, sim.history

Function to interactively label nodes of a plotted tree

Description

Adds node labels to a plotted object of class "phylo".

Usage

labelnodes(text, node=NULL, interactive=TRUE, shape=c("circle","ellipse",
   "rect"), ...)

Arguments

Details

The nodes to be labels can be selected interactively by the user (i.e., by clicking on the corresponding nodes of the plotted tree).

Value

Invisibly returns a vector of the node indices for the labeled nodes.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

cladelabels, nodelabels

Ladderize a tree with a mapped discrete character

Description

Ladderizes an object of class "simmap".

Usage

ladderize.simmap(tree, right=TRUE)

Arguments

Details

This function 'ladderizes' an object of class "simmap" with a mapped discrete character.

For more information see ladderize.

Value

A ladderized object of class "simmap".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

make.simmap, ladderize

Examples

## load "simmap" object
data(anoletree)

## ladderize object
anoletree_ladderized<-ladderize.simmap(anoletree)

## plot unladderized & ladderized
par(mfrow=c(2,1))
plot(anoletree,ftype="off",direction="upwards",
    mar=c(1.1,2.1,2.1,1.1))
mtext("a) unladderized tree",adj=0)
plot(anoletree_ladderized,ftype="off",
    direction="upwards",mar=c(1.1,2.1,2.1,1.1))
mtext("b) ladderized tree",adj=0)

## reset par to default
par(mfrow=c(1,1),mar=c(5.1,4.1,4.1,2.1))

\lambda transformation of matrix

Description

Internal function for phyl.pca and others.

Usage

lambda.transform(lambda, C)

Arguments

Details

Multiplies the off-diagonals of a square matrix by lambda and returns the result.

Value

Typically an among-species phylogenetic variance covariance matrix (e.g., vcv.phylo) in which the off-diagonal elements have been multiplied by lambda.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Likelihood for joint \lambda

Description

Likelihood function for joint estimation of Pagel's \lambda parameter.

Usage

likMlambda(lambda, X, C)

Arguments

Details

Generally intended to be used internally by other methods that do joint optimization of \lambda (e.g., phyl.pca).

Value

The log-likelihood.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Function to add tip labels to a plotted tree with linking lines

Description

Adds tip labels to a plotted tree by drawing curved, bent, or straight linking lines.

Usage

linklabels(text,tips,link.type=c("bent","curved","straight"),
   ...)

Arguments

Details

The idea underlying this function is that the user should first plot the tree without tip labels, but set the area of the plotting device to be sufficient to accommodate the tip labels once they have been added. The function then can be called to add tip labels connected by linking lines to the tips of the plotted tree.

Value

This function annotates a plot.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

cladelabels, nodelabels, tiplabels

Locate a fossil lineage in a tree using continuous characters

Description

Uses ML to place a fossil lineage into a tree using continuous traits following Revell et al. (2015).

Usage

locate.fossil(tree, X, ...)

Arguments

Value

Optimized tree as an object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (1981) Maximum likelihood estimation of evolutionary trees from continuous characters. American Journal of Human Genetics, 25, 471-492.

Felsenstein, J. (2002) Quantitative characters, phylogenies, and morphometrics. In: MacLeod, N. and P. Forey (Eds.) Morphology, Shape and Phylogeny (pp. 27-44). Taylor and Francis, London.

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

Revell, L. J., D. L. Mahler, R. G. Reynolds, and G. J. Slater. (2015) Placing cryptic, recently extinct, or hypothesized taxa into an ultrametric phylogeny using continuous, character data: A case study with the lizard Anolis roosevelti. Evolution, 69, 1027-1035.

Locate a cryptic, recently extinct, or missing taxon on a tree

Description

Uses ML (or REML) to place a recently extinct, cryptic, or missing taxon on an ultrametric (i.e., time-calibrated) phylogeny following Revell et al. (2015).

Usage

locate.yeti(tree, X, ...)

Arguments

Value

Optimized tree as an object of class "phylo".

Author(s)

Liam Revell liam.revell@umb.edu

References

Felsenstein, J. (1981) Maximum likelihood estimation of evolutionary trees from continuous characters. American Journal of Human Genetics, 25, 471-492.

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

Revell, L. J., D. L. Mahler, R. G. Reynolds, and G. J. Slater. (2015) Placing cryptic, recently extinct, or hypothesized taxa into an ultrametric phylogeny using continuous, character data: A case study with the lizard Anolis roosevelti. Evolution, 69, 1027-1035.

Least squares branch lengths for a given tree

Description

Computes the least squares branch lengths conditioned on a topology and distance matrix.

Usage

ls.tree(tree, D)

Arguments

Details

Generally intended as a function to be used internally by optim.phylo.ls.

Value

A tree with branch lengths.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

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

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:

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 liam.revell@umb.edu

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)

Creates a (1-\alpha)% CI for a set of LTTs

Description

This function computes LTT plots for a set of trees & plots a (1-\alpha)% CI by various methods. (See ltt for more details.)

Usage

ltt95(trees, alpha=0.05, log=FALSE, method=c("lineages","times"),
   mode=c("median","mean"), ...)
## S3 method for class 'ltt95'
plot(x, ...)

Arguments

Details

This function creates a plot and invisibly returns an object of class "ltt95".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

ltt

Create "era" map on a phylogenetic tree

Description

Creates a temporal map on the tree based on limits provided by the user.

Usage

make.era.map(tree, limits, ...)

Arguments

Value

An object of class "simmap" with the specified eras mapped as different regimes.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

make.simmap, read.simmap, plotSimmap

Examples

## simulate tree with total depth of 100
tree<-pbtree(n=1000,scale=100)

## subdivide into mapped eras
tree<-make.era.map(tree,c(0,25,50,75))

## create graph of mapped tree
plot(tree,ftype="off",lwd=1)

## reset margins to default
par(mar=c(5.1,4.1,4.1,2.1))

Simulate stochastic character maps on a phylogenetic tree or trees

Description

Performs stochastic character mapping (Huelsenbeck et al., 2003) using several different alternative methods.

Usage

make.simmap(tree, x, model="SYM", nsim=1, ...)
simmap(object, ...)

Arguments

Details

For Q="empirical", make.simmap first fits a continuous-time reversible Markov model for the evolution of x and then simulates stochastic character histories using that model and the tip states on the tree. This is the same procedure that is described in Bollback (2006), except that simulation is performed using a fixed value of the transition matrix, Q, instead of by sampling Q from its posterior distribution.

For Q="mcmc", make.simmap first samples Q nsim times from the posterior probability distribution of Q using MCMC, then it simulates nsim stochastic maps conditioned on each sampled value of Q.

For Q set to a matrix, make.simmap samples stochastic mappings conditioned on the fixed input matrix.

make.simmap uses code that has been adapted from ape's function ace (by Paradis et al.) to perform Felsenstein's pruning algorithm to compute the likelihood.

As of phytools >= 0.2-33 x can be a vector of states or a matrix containing the prior probabilities of tip states in rows. In this case the column names of x should contain the states, and the row names should contain the tip names.

Note that there was a small (but potentially significant) bug in how node states were simulated by make.simmap in versions of phytools <= 0.2-26. Between phytools 0.2-26 and 0.2-36 there was also a bug for asymmetric models of character change (e.g., model="ARD"). Finally, between phytools 0.2-33 and phytools 0.2-47 there was an error in use of the conditional likelihoods for the root node, which caused the root node of the tree to be sampled incorrectly. Giorgio Bianchini pointed out that in phytools 1.0-1 (and probably prior recent versions) there was an error sampling the state at the root node of the tree based on the input prior (pi) supplied by a user – except for pi="equal" (a flat prior, the default) or for a prior distribution in which one or another state was known to be the global root state (e.g., pi=c(1,0), pi=c(0,1), etc.). All of these issues should be fixed in the current and all later versions.

If tree is an object of class "multiPhylo" then nsim stochastic maps are generated for each input tree.

Value

A object of class "simmap" or "multiSimmap" which consists of an object of class "phylo" (or a list of such objects with class "multiPhylo"), with the following additional elements:

Author(s)

Liam Revell liam.revell@umb.edu

References

Bollback, J. P. (2006) Stochastic character mapping of discrete traits on phylogenies. BMC Bioinformatics, 7, 88.

FitzJohn, R. G., W. P. Maddison, and S. P. Otto (2009) Estimating trait-dependent speciation and extinction rates from incompletely resolved phylogenies. Systematic Biology, 58, 595-611.

Huelsenbeck, J. P., R. Neilsen, and J. P. Bollback (2003) Stochastic mapping of morphological characters. Systematic Biology, 52, 131-138.

Paradis, E., J. Claude, and K. Strimmer (2004) APE: Analyses of phylogenetics and evolution in R language. Bioinformatics, 20, 289-290.

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

Revell, L. J. and L. J. Harmon (2022) Phylogenetic Comparative Methods in R. Princeton University Press.

See Also

ancr, brownie.lite, brownieREML, countSimmap, describe.simmap, evol.vcv, plotSimmap, read.simmap, write.simmap

Examples

## Not run: 
## load tree and data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract discrete character (feeding mode)
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))
  
## fit model
er_model<-fitMk(sunfish.tree,fmode,model="ER",
    pi="fitzjohn")
	
## do stochastic mapping
sunfish_smap<-simmap(er_model)

## print a summary of the stochastic mapping
summary(sunfish_smap)

## plot a posterior probabilities of ancestral states
cols<-setNames(c("blue","red"),levels(fmode))
plot(summary(sunfish_smap),colors=cols,ftype="i")
legend("topleft",c("non-piscivorous","piscivorous"),
    pch=21,pt.bg=cols,pt.cex=2)
par(mar=c(5.1,4.1,4.1,2.1),las=1)

## plot posterior density on the number of changes
plot(density(sunfish_smap),bty="l")
title(main="Posterior distribution of changes of each type",
    font.main=3)
## reset par to default
par(las=0)
## End(Not run)

Proportional overlap between two mapped character histories on a tree

Description

Calculates the similarity of two different stochastically mapped character histories.

Usage

map.overlap(tree1, tree2, tol=1e-6, ...)
Map.Overlap(tree1, tree2, tol=1e-06, standardize=TRUE, ...)

Arguments

Details

map.overlap computes a single quantity giving the overall similarity of the maps, consequently this measure only makes sense of some or all of the states are shared between the two mapped tress.

In Map.Overlap what is computed instead is a matrix in which the rows correspond to the states observed in tree1 and the columns give the states for tree2, with the numerical values of the matrix showing the total overlap between each pair of mapped states on the two trees.

Value

A numerical value on the interval (0, 1), for map.overlap; or a matrix whose elements should sum to 1.0 (Map.Overlap).

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

make.simmap, read.simmap

Converts a tree without singletons to a tree with singleton nodes

Description

map.to.singleton takes an object of class "simmap" with a mapped discrete character and converts it to a tree with singleton nodes, in which edge has only one state.

Usage

map.to.singleton(tree)
plotTree.singletons(tree)
## S3 method for class 'singleton'
drop.tip(phy, tip, ...)
rootedge.to.singleton(tree)

Arguments

Details

The states for each edge are stored in names(tree$edge.length). In a sense this is just an alternative way to use the general structure of the "phylo" object to encode a tree with a mapped character.

plotTree.singletons plots a tree with singleton nodes. Note that plotTree and plot.phylo now have no trouble graphing trees with singleton nodes - but they do this by just ignoring the singletons. plotTree.singletons marks the singletons as nodes on the plotted phylogeny.

drop.tip.singleton drops tips from the tree leaving ancestral nodes for all remaining tips as singletons.

Finally, rootedge.to.singleton converts a tree with a root edge to a tree with a singleton node instead.

Value

An object of class "phylo" with singleton nodes. plotTree.singletons graphs a tree in which the singleton nodes are shown.

If names(tree$edge.length)!=NULL plotTree.singletons will use a different color from palette for each mapped state.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

collapse.singles, drop.tip, make.simmap

Returns a vector, matrix, or list of the mapped states on a tree or set of trees

Description

Computes and orders a vector, matrix, or list of the unique mapped states on a tree or state of trees of class "simmap" or "multiSimmap".

Usage

mapped.states(tree, ...)

Arguments

Value

A vector, matrix, or list.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Add marked changes to a plotted tree with mapped discrete character

Description

Adds the reconstructed changes to a plotted tree with a stochastically mapped discrete character.

Usage

markChanges(tree, colors=NULL, cex=1, lwd=2, plot=TRUE)

Arguments

Value

This function returns (invisibly) a matrix containing the x & y coordinates of the marked changes on the plotted tree.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

plotSimmap

Examples

## load tree and data from Revell & Collar (2009)
data(sunfish.tree)
data(sunfish.data)

## extract discrete character (feeding mode)
fmode<-setNames(sunfish.data$feeding.mode,
    rownames(sunfish.data))

## fit model
er_model<-fitMk(sunfish.tree,fmode,model="ER",
    pi="fitzjohn")

## generate single stochastic map
sunfish_smap<-simmap(er_model,nsim=1)

## plot stochastic map & mark changes
cols<-setNames(c("blue","red"),levels(fmode))
plot(sunfish_smap,cols,ftype="i")
markChanges(sunfish_smap,colors=cols,lwd=6)

## reset par to default
par(mar=c(5.1,4.1,4.1,2.1))

Matches nodes between two trees

Description

This function returns a matrix in which the first column contains all of the internal nodes of tr1 and the second column contains the matching nodes from tr2, inasmuch as they can be identified.

Usage

matchNodes(tr1, tr2, method=c("descendants","distances"), ...)
matchLabels(tr1, tr2)

Arguments

Details

For method="descendants", pairs of matching nodes are defined by sharing all descendant leaves in common.

For method="distances", nodes are considered to matched if the share the same set of distances (or proportional distances, for optional argument corr=TRUE) to all tips.

matchLabels is functionally equivalent but matches node (tip) indices based on identifying matching in the labels only.

Value

A matrix in which the first column contains the nodes of tr1 with the second column containing matching nodes in tr2, with the criterion for matching defined by method.

Author(s)

Liam Revell liam.revell@umb.edu

References

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

Merge two or more mapped states into one state

Description

Merges two or mapped states on the tree to get one new state.

Usage

mergeMappedStates(tree, old.states, new.state)

Arguments

Details

mergeMappedStates can be used to merge two or more mapped states into a single, new state. For instance, one could merge the states "C", "G", and "T" and define the new the state "not-A".

Value

An object of class "simmap" or "multiSimmap".

Author(s)

Liam Revell liam.revell@umb.edu

References

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

See Also

make.simmap, read.simmap

Midpoint root a phylogeny

Description

These functions midpoint root a rooted or unrooted tree (Farris 1972).

Usage

midpoint_root(tree)
## S3 method for class 'root'
midpoint(tree, node.labels="support", ...)

Arguments