ML.RatePhylo: Maximum likelihood rate estimation for traits and phylogenies
In ghthomas/motmot: Models of Trait Macroevolution on Trees

Description Usage Arguments Value Note Author(s) References Examples

Full function for maximum likelihood estimation of rate parameters and comparison to a single rate model.

1 2	ML.RatePhylo(rateData, rate = NULL, fixed = NULL, pretty = TRUE, rateMIN = 0.001, rateMAX = 50, common.mean = FALSE, lambda.est=TRUE, est.CI=FALSE, meserr=FALSE, file=NULL)

`rateData`	an object of class "rateData"
`rate`	a vector of relative rate parameters. The length of the vector is equal to the number of rates being estimated. If `rate=NULL` then rates are equal.
`fixed`	A vector stating whether each parameter should be allowed to vary (either `FALSE` which results in a start value of 1, or a numeric start value) or should be fixed (`TRUE`).
`pretty`	Display the output nicely (`pretty=TRUE`) or as a list (`pretty=FALSE`)
`rateMIN`	Minimum value for the rate parameters
`rateMAX`	Maximum value for the rate parameters
`common.mean`	a logical specififying whether each rate category should have its own mean (`common.mean=FALSE`) or all categories should have the same mean (`common.mean=FALSE`). See Thomas et al. (2009) for a discussion on the impact of assumptions about mean on rate estimates.
`lambda.est`	Logical. Estimate Pagel's lambda.
`est.CI`	Logical. Estimate approximate confidence intervals for rate parameters.
`meserr`	Logical. Incorporate measurement error.
`file`	File string for output. Only used if `pretty=TRUE`.

If pretty=FALSE, returns a list containing:

`MLRate`	Maximum likelihood estimates of the rate parameters
`Lambda`	Maximum likelihood estimate of lambda
`LCI`	Approximate lower confidence intervals for rate
`UCI`	Approximate upper confidence intervals for rate parameters
`means`	Means for each category
`nParam`	Number of parameters in the model (how many means and rate categories)
`Max.lik`	Maximum (log) likeihood
`AIC`	AIC for maximum likelihood model
`AICc`	AICc for maximum likelihood model
`LambdaSingle`	Maximum likelihood estimate of lambda for the single rate model
`Lik1`	Likelihood of the equivalent single rate model
`LR`	Likelihood ratio statistic of "Max.lik" vs "Lik1"
`P`	P values for the LR statistic
`df`	Degrees of freedom for the LR statistic
`AIC.rate1`	AIC for single rate model
`AICc.rate1`	AICc for single rate model

If pretty=TRUE, prints a nice version of the list to screen. If file is specified the pretty output will be sent to file, not the console.

Unlike phyloMean and likRatePhylo (that use treatment contrasts), the means reported here are the actual values

Gavin Thomas, Rob Freckleton

Thomas GH, Freckleton RP, & Szekely T. 2006. Comparative analyses of the influence of developmental mode on phenotypic diversification rates in shorebirds. Proceedings of the Royal Society B 273, 1619-1624.

Thomas GH, Meiri S, & Phillimore AB. 2009. Body size diversification in Anolis: novel environments and island effects. Evolution 63, 2017-2030.

## Read in phylogeny and data from Thomas et al. (2009)
data(anolis.tree)
data(anolis.data)

## Convert data to class rateData with a rateMatrix object as input
anolis.rateMatrix <- as.rateMatrix(phy=anolis.tree, x="geo_ecomorph", data=anolis.data)

anolis.rateData <- as.rateData(y="Female_SVL", x="geo_ecomorph", 
rateMatrix = anolis.rateMatrix, phy=NULL, data=anolis.data, log.y=TRUE)

# A model with a different rate in each of the four groups. The 'fixed' command is used to determine
# whether a particular rate is to be constrained or not. Use '1' to fix a group and 'FALSE' to show
# that the parameter is not fixed and should be estimated. The values should be entered in the same 
# order as the ranking of the groups. That is, group 0 (small islands) takes position one in the 
# fixed vector, group 1 (large island trunk crown and trunk ground) takes position 2 and so on. 
# The default is to allow each group to take a different mean. 

# Not run
# ML.RatePhylo(anolis.rateData, fixed=c(1,FALSE,FALSE, FALSE), pretty=TRUE)


# A different model, force small islands, large island other, and mainland to be 1 and only estimate
# large island trunk crown and trunk ground 
# Not run
# ML.RatePhylo(anolis.rateData, fixed=c(1,FALSE,1, 1), pretty=TRUE)


# Run the same two models, but this time assuming a common mean across all four groups
# Not run
# ML.RatePhylo(anolis.rateData, fixed=c(1,FALSE,FALSE, FALSE), pretty=TRUE, common.mean=TRUE)
# ML.RatePhylo(anolis.rateData, fixed=c(1,FALSE,1, 1), pretty=TRUE, common.mean=TRUE)