evorates: evorates: Fitting continuously variable rate models to...
In bstaggmartin/evorates: Evolving Rate Models of Continuous Trait Evolution

evorates

R Documentation

evorates: Fitting continuously variable rate models to comparative data on continuous traits

Description

This package implements a Bayesian method for fitting "relaxed" models of continuous trait evolution to comparative data (i.e., a phylogeny and associated trait data), whereby the rate of trait evolution itself gradually changes over time and across lineages. More details on the model and method can be found in the associated manuscript. The package provides additional tools for simulating data, as well as manipulating, analyzing, and visualizing estimated model parameters. Below is a broad overview of the available functions in this package:

Basic functions

To simulate data, use sim.evorates().
To fit data to models, use fit.evorates() (which is a wrapper for the functions input.evorates(), run.evorates(), and output.evorates(), which may be used to provide finer control over certain aspects of the model fitting process).
To check that fitted model converged and sampled posterior distributions adequately, use check.mix() and check.ess().
To subset, combine, or thin Hamiltonian Monte Carlo chains in a fitted model, use select.chains(), combine.chains(), exclude.warmup(), and thin.chains().

Analysis functions

To calculate Savage-Dickey raitos and see if a fitted model yields "substantial" evidence for rate heterogeneity, use get.sd().
For extraction, summarization, and manipulation of posterior samples (including calculating posterior probabilities!), see documentation on the param_block class and associated documentation on the param_block operators %chains%(), %quantiles%(), %means%(), %diagnostics%(), and %select%(), as well as the functions par.c() (for combining parameter blocks), rnorm.par() (for generating parameter blocks of normal random samples), and pwc() (for doing pairwise comparisons among parameter blocks).
For convenient extraction of average rates along each branch, use get.R().
To "adjust" rates for trends, use remove.trend().
To calculate "background rates" and summarize rates over different parts of a phylogeny, use get.bg.rate().
To sample posterior distributions of trait values at nodes (i.e., ancestral state estimation) in a phylogeny given a fitted model, use get.post.traits().

Plotting functions

There are plotting methods for simulated data and fitted models; see plot.evorates() and plot.evorates_fit() (NOTE: documentation still under construction).
You WILL be able to plot plots of posterior samples vs. chain iterations ("traces") very soon using trace.plot()!
You can plot histograms/density plots ("profiles") of posterior samples using prof.plot().
A lot of these functions rely on a nice little helper function alter.cols(), which can be used to mix a vector of colors with other colors or modify transparency.
I plan on developing another function some day, perhaps called level.plot() or something like that, which will plot 2D histograms/density plots similarly to smoothScatter() and contour(). The idea is to be able to look at posterior correlations among parameter estimates.

Miscellaneous functions (NOTE

documentation still largely under construction):

Use get.clade.edges() to extract the edge indices in a phylogeny associated with a particular clade (defined by either its most recent common ancestor or a group of tip labels). You can also use exclude.clade() to take edges associated with some nested subclade out of a larger clade.
The function edge.vcv() calculates the "edgewise" variance-covariance matrix of a phylogeny. Normally, phylogenetic variance-covariance matrices describe the covariance structure of trait values at nodes expected under a Brownian Motion model. Edgewise variance-covariance matrices instead describe the covariance structure of average trait values along each branch expected under a Brownian Motion model.
Some functions rely a nice helper function, multi.bind.tip(), which wraps and generalizes the phytools function bind.tip() to handle binding multiple tips to a phylogeny at once.
There are Ntip(), Nedge(), and Nnode() methods for simulated data and fitted models to quickly extract these quantities as necessary.
Further, there are some new convenient methods for extracting topological information from phylogenies, simulated data, and fitted models:
- Use edge.ranges() to get start and end times of each edge in a phylogeny in matrix form (with a row for each edge and two columns for start and end times).
- There are new edgewise "tree-walking" functions for getting edge indices corresponding to the ancestor, descendants, or sisters for each edge in a phylogeny: anc.edges(), des.edges(), and sis.edges().
- You can use tip.edges() to get the edge indices for each tip in a phylogeny and root.edges() to get indices of edges descending from the root node.
- Lastly, you can use ladder() to "ladderize" edges in a phylogeny. In the context of simulated data and fitted evorates models, this also rearranges edgewise information like branchwise rates accordingly.