transformPhylo.MCMC: Bayesian MCMC for models of trait evolution
In motmot.2.0: Models of Trait Macroevolution on Trees

Description Usage Arguments Details Value Author(s) Examples

Fits Bayesian models for various models of continuous character evolution using a Metropolis-Hastings Markov Chain Monte Carlo (MCMC) approach

transformPhylo.MCMC(y, phy, model, mcmc.iteration = 1000, burn.in = 0.1,
  hiddenSpeciation = FALSE, full.phy = NULL, lowerBound = NULL,
  upperBound = NULL, opt.accept.rate = TRUE, acceptance.sd = NULL,
  opt.prop = 0.25, fine.tune.bound = 0.05, fine.tune.n = 30,
  useMean = FALSE, random.start = TRUE)

`y`	A matrix of trait values.
`phy`	An object of class "phylo" (see ape package).
`model`	The model of trait evolution (see details).
`mcmc.iteration`	Integer - the number of generations for which to run the MCMC chain
`burn.in`	The proportion of the chain (as given by mcmc.iteration) which to discard as 'burn-in'
`hiddenSpeciation`	Logical. If TRUE the psi model will include nodes that are on the 'full.phy' but not the tree pruned of trait data
`full.phy`	The full phylogeny containing the species that do not contain trait data so are not included in 'phy'
`lowerBound`	Minimum value for parameter estimates
`upperBound`	Maximum value for parameter estimates
`opt.accept.rate`	Logical. Perform a pre-run optimisation to achieve an acceptance rate close to 0.44?
`acceptance.sd`	Numeric. The starting standard deviation for the proposal distribution
`opt.prop`	The proportion of the mcmc.iteration with which to optimise the acceptance rate.
`fine.tune.bound`	The distance (+/-) from the optimal acceptance rate of 0.44 at which the fine-tune algorithm will stop. Default = 0.05.
`fine.tune.n`	The number of iterations with which to optimise the acceptance rate.
`useMean`	Logical. Use the branch-based estimates of extinction of mean (TRUE, default) for the "psi" and "multispi" models only applicable if "hiddenSpeciation" = TRUE
`random.start`	Use a random starting value for the MCMC run (TRUE), or use the environment set.seed() value

fine.tune.n The method estimates posterior probabilities using a Metropolis-Hastings MCMC approach. To aide convergence, the model will attempt to reach an acceptable proposal ratio (~0.44) when opt.accept.rate=TRUE. These initial fine-tune repititions only save the standard deviation for the truncated normal distribution that is used for the proposal mechanism. The chain is discarded. Posterior probabilites and MCMC diagnostics come from the seperate output chain that commences after this fine-tune procedure. The MCMC model will estimate the posterior probability for the following models.

model="kappa" fits Pagel's kappa by raising all branch lengths to the power kappa. As kappa approaches zero, trait change becomes focused at branching events. For complete phylogenies, if kappa approaches zero this infers speciational trait change. Default bounds from ~0 - 1.
model="lambda" fits Pagel's lambda to estimate phylogenetic signal by multiplying all internal branches of the tree by lambda, leaving tip branches as their original length (root to tip distances are unchanged). Default bounds from ~0 - 1.
model="delta" fits Pagel's delta by raising all node depths to the power delta. If delta <1, trait evolution is concentrated early in the tree whereas if delta >1 trait evolution is concentrated towards the tips. Values of delta above one can be difficult to fit reliably. Default bounds from ~0 - 5.
model="OU" fits an Ornstein-Uhlenbeck model - a random walk with a central tendency proportional to alpha. High values of alpha can be interpreted as evidence of evolutionary constraints, stabilising selection or weak phylogenetic signal. It is often difficult to distinguish among these possibilities. Default bounds from ~0 - 10.
model="psi" fits a acceleration-deacceleration model to assess to the relative contributions of speciation and gradual evolution to a trait's evolutionary rate (Ingram 2010).
model="ACDC" fits a model to in which rates can exponentially increased or decrease through time (Blomberg et al. 2003). If the upper bound is < 0, the model is equivalent to the 'Early Burst' model of Harmon et al. 2010. Default rate parameter bounds from ln(1e-10) ~ ln(20) divided by the root age.

median The median estimate of the posterior for the parameter

95.HPD The 95 percent Highest Posterior Density for the parameter

ESS Effective Sample Size for the posterior

acceptance.rate The ratio for which new proposals were accepted during the MCMC chain

mcmc.chain Full MCMC chain containing all iterations (including burn-in)

Mark Puttick, Gavin Thomas

data(anolis.tree)
data(anolis.data)
attach(anolis.data)
male.length <- matrix(Male_SVL, dimnames=list(rownames(anolis.data)))
sortedData <- sortTraitData(anolis.tree, male.length)
phy <- sortedData$phy
male.length <- sortedData$trait
phy.clade <- extract.clade(phy, 182)
male.length.clade <- as.matrix(male.length[match(phy.clade$tip.label, rownames(male.length)),])
## please note, this model will be need to run for longer to achieve convergence
lambda.mcmc <- transformPhylo.MCMC(y=male.length.clade, phy=phy.clade, 
model="lambda", mcmc.iteration=100, burn.in=0.1)