phytools (version 2.3-0)

multirateBM: Function to fit a multi-rate Brownian evolution model

Description

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

Usage

multirateBM(tree, x, method=c("ML","REML"), 
    optim=c("L-BFGS-B","Nelder-Mead","BFGS","CG"),
    maxit=NULL, n.iter=1, lambda=1, ...)

Value

An object of class "multirateBM".

Arguments

tree

an object of class "phylo".

x

a named numerical vector. Names should correspond to the species names of tree.

method

method of optimization. Currently only method="ML".

optim

optimization routine to be used by optim. If more than one is specified and n.iter>1 then they will be alternated. (This is recommended to improve optimization.)

maxit

to be passed to optim. If set to maxit=NULL, the default value of maxit will be used, depending on the optimization method.

n.iter

number of times to reiterate failed optimization.

lambda

lambda penalty term. High values of lambda correspond to high penalty for rate heterogeneity among edges. Low values of lambda correspond to low penalty.

...

optional arguments.

Author

Liam Revell

Details

This function fits a flexible Brownian multi-rate model using penalized likelihood.

The model that is being fit is one in which the rate of Brownian motion evolution itself evolves from edge to edge in the tree under a process of geometric Brownian evolution (i.e., Brownian motion evolution on a log scale).

The penalty term, lambda, determines the cost of variation in the rate of evolution from branch to branch. If lambda is high, then the rate of evolution will vary relatively little between edges (and in the limiting case converge to the single-rate MLE estimate of the rate). By contrast, if the value of lambda is set to be low, then the rate of evolution can vary from edge to edge with relatively little penalty.

Decreasing the penalty term, however, is not without cost. As lambda is decreased towards zero, estimated rates will tend to become less and less accurate.

References

Revell, L. J. (2021) A variable-rate quantitative trait evolution model using penalized-likelihood. PeerJ, 9, e11997.

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.rate.mcmc

Examples

if (FALSE) {
## load data
data(sunfish.tree)
data(sunfish.data)
## convert from "simmap" to "phylo"
sunfish.tree<-as.phylo(sunfish.tree)
## extract character of interest
gw<-setNames(sunfish.data$gape.width,
    rownames(sunfish.data))
## run penalized-likelihood optimization
## lambda=0.1 is arbitrary
fitBM<-multirateBM(sunfish.tree,gw,
    lambda=0.01)
## print and plot the results
print(fitBM)
plot(fitBM,ftype="i",fsize=0.8,lwd=6,
    outline=TRUE)
## reset par
par(mar=c(5.1,4.1,4.1,2.1))}