fit_t_standard {RPANDA}

Fits standard models of trait evolution incorporating known and nuisance measurement error

Description

Fits Brownian motion (BM), Ornstein-Uhlenbeck (OU), or early burst (EB) models of trait evolution to a given dataset and phylogeny.

Usage

fit_t_standard(phylo, data, model=c("BM","OU","EB"), error=NULL, two.regime=FALSE, 
		method="Nelder-Mead", echo=TRUE, ...)

Arguments

phylo

an object of type 'phylo' (see ape documentation); if two.regime=TRUE, this must be a simmap object from make.simmap with two regimes

data

a named vector of trait values with names matching phylo$tip.label

model

model chosen to fit trait data, "BM" is the Brownian motion model, "OU" is the Ornstein-Uhlenbeck model, and "EB" is the early burst model.

error

A named vector with standard errors (SE) of trait values for each species (with names matching "phylo$tip.label"). The default is NULL, in this case potential error is ignored in the fit. If set to NA, the SE is estimated from the data (to be used when there are no error measurements, a nuisance parameter is estimated). Note: When standard errors are provided, a nuisance parameter is also estimated.

two.regime

if TRUE, fits a two-regime model

method

optimization method from link{optim}

echo

prints information to console during fit

...

Optional arguments. e.g. "upper=xx", "lower=xx" to specify bounds on the parameter search. "fixedRoot=TRUE" to use an OU model where the root state is assumed fixed (instead of sampled from the stationary distribution)

Details

Note: if including known measurement error, the model fit incorporates this known error and, in addition, estimates an unknown, nuisance contribution to measurement error. The current implementation does not differentiate between the two, so, for instance, it is not possible to estimate the nuisance measurement error without providing the known, intraspecific error values.

Value

a list with the following elements:

LH

maximum log-likelihood value

aic

Akaike Information Criterion value

aicc

AIC value corrected for small sample size

free.parameters

number of free parameters from the model

sig2

maximum-likelihood estimate of sig2 parameter

alpha

maximum-likelihood estimate of alpha parameter of OU model (see Note)

r

maximum-likelihood estimate of the slope parameter of early burst model

z0

maximum-likelihood estimate of z0, the value at the root of the tree

nuisance

maximum-likelihood estimate of nuisance, the unknown, nuisance contribution to measurement error (see details)

convergence

convergence diagnostics from optim function (see optim documentation)

Author(s)

Jonathan Drury [e-mail]

Julien Clavel

See Also

fit_t_comp sim_t_tworegime

Examples

if(test){
data(Cetacea_clades)
data<-sim_t_tworegime(Cetacea_clades,pars=c(sig2=0.01,r1=-0.01,r2=-0.02),
	root.value=0,Nsegments=1000,model="EB")
error<-rep(0.05,length(Cetacea_clades$tip.label))
names(error)<-Cetacea_clades$tip.label

#Fit single-regime models
BM1.fit<-fit_t_standard(Cetacea_clades,data,model="BM",error,two.regime=FALSE)
OU1.fit<-fit_t_standard(Cetacea_clades,data,model="OU",error,two.regime=FALSE)
EB1.fit<-fit_t_standard(Cetacea_clades,data,model="EB",error,two.regime=FALSE)

#Now fit models that incorporate biogeography, NOTE these models take longer to fit
BM2.fit<-fit_t_standard(Cetacea_clades,data,model="BM",error,two.regime=TRUE)
OU2.fit<-fit_t_standard(Cetacea_clades,data,model="OU",error,two.regime=TRUE)
EB2.fit<-fit_t_standard(Cetacea_clades,data,model="EB",error,two.regime=TRUE)
  }