phytools (version 2.1-1)

fitPagel: 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 fitPagel
plot(x, ...)

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.

Arguments

tree

an object of class "phylo".

x

a vector of phenotypic values for a binary trait for the species in tree; or a matrix in which the rows of x give the probability of being in each column state. (The latter option is only supported for method="fitMk".) For S3 plot method, an object of class "fitPagel".

y

a second binary character for the species in tree; or a matrix in which the rows give the probability of being in each column state.

method

function to use for optimization (defaults to method="fitMk"). Other options are "ace" to use the ace function in ape for optimization, or to "fitDiscrete" (if the geiger package is installed) to use geiger's fitDiscrete for optimization.

model

model of evolution for the individual characters. Can be model="ER", "SYM" (equivalent to "ER" in this case), and "ARD".

dep.var

dependent variable. If dep.var="xy" than the rate of substitution in x depends on y & vice versa. If dep.var="x" than the substitution rate in x depends on y, but not the converse. Finally, if dep.var="y" than the rate of substitution in y depends on x, but not the converse.

...

optional arguments to be passed to fitMk, ace, or fitDiscrete. For plot method optional arguments include (but may not be limited to): signif, the number of digits for the rates to be plotted; main, a character vector of length two with the headings for each subplot; cex.main, cex.sub, cex.traits, and cex.rates, font sizes for the various text elements of the plot; and lwd.by.rate, a logical argument specifying whether or not to scale arrow line widths in proportion to the estimated rates.

Author

Liam Revell

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.

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

if (FALSE) {
## 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))}