RateScape: Detecting and Explaining Rate Heterogeneity in Discrete Character Evolution

Overview

RateScape provides a unified, user-friendly framework for modeling discrete character evolution on phylogenies. The package implements a spike-and-slab mixture model with reversible-jump MCMC for detecting branch-specific rate variation—revealing which parts of a tree evolve faster or slower than others. But RateScape is much more than rate detection: it bundles reimplementations and extensions of classic comparative methods spanning two decades of evolutionary biology.

Whether you're fitting simple Mk models (Lewis 2001), testing for hidden evolutionary rates (Beaulieu et al. 2013), applying Pagel's tree transformations and correlated evolution test, computing the Fritz & Purvis D statistic for phylogenetic signal, running phylogenetic logistic regression (Ives & Garland 2010), fitting the threshold model (Wright 1934; Revell 2014), handling polymorphic tips, generating stochastic character maps, or modeling gamma rate categories—RateScape handles all of it with a consistent, intuitive API. The package is optimized for speed via eigendecomposition caching and tree traversal pre-computation, with planned C++ backends for even faster inference.

Automatic model selection, posterior predictive diagnostics, and covariate effect analysis make it easy to move from raw data to biological insight without wrestling with implementation details.

Installation

Install the development version from GitHub:

# Install devtools if needed
# install.packages("devtools")
devtools::install_github("coleoguy/RateScape", build_vignettes = TRUE)

Quick Start

Here's a minimal workflow to get you up and running:

library(RateScape)
library(ape)

# Simulate a phylogeny and discrete character data
tree <- rtree(50)
Q <- matrix(c(-1, 1, 1, -1), 2, 2)
sim <- simRateScape(tree, Q, nrep = 1, r_scalars = rep(1, nrow(tree$edge)))
data <- data.frame(state = sim$data$state - 1, row.names = sim$data$tip)

# Fit a basic Mk model
mk_fit <- fitQ(tree, data, model = "mk", method = "ml")

# Perform ancestral state reconstruction
anc <- ancestralStates(tree, data, Q = mk_fit$Q_mle)

# Test for branch-specific rate variation
rate_model <- fitRateScape(tree, data, Q = mk_fit$Q_mle)

# Compare models
comparison <- compareModels(mk_fit, rate_model,
                            model_names = c("Mk", "RateVar"))

Key Functions

Function	Description
Model Fitting
fitQ	Fit Mk models (ER, ARD, SYM) with optional rate categories
fitQstructure	Discover Q-matrix structure via reversible-jump MCMC
fitRateScape	Detect branch-specific rate heterogeneity via spike-and-slab MCMC
fitHRM	Fit hidden rate Markov models
fitMultiRegime	Fit multi-regime Q-matrix models (shifts across clades)
fitThreshold	Fit Felsenstein/Revell threshold model for discrete traits
fitPolyMk	Fit Mk models with polymorphic tip states
Tree Transformations & Tests
fitTreeTransform	Apply Pagel's lambda, delta, kappa transformations
fitCorrelated	Pagel's test for correlated evolution of two characters
phyloSignalD	Fritz & Purvis D statistic for phylogenetic signal
phyloGLM	Phylogenetic logistic regression (PGLS for discrete traits)
Utilities & Diagnostics
ancestralStates	Estimate ancestral character states
simmapRate	Stochastic character mapping with rate-aware sampling
rateCategories	Estimate gamma-distributed rate heterogeneity via EM
compareModels	Compare fitted models by AIC, BIC, or LRT
autoModel	Automatic model selection and comparison
posteriorPredictive	Posterior predictive model adequacy checks
covariateEffects	Analyze covariate effects on evolution
simRateScape	Simulate discrete character data on phylogenies

Citation

When using RateScape, please cite the package:

citation("RateScape")

Users should also cite the original method papers corresponding to functions they use. See ?fitRateScape, ?fitTreeTransform, etc. for relevant citations.

Acknowledgments

RateScape builds upon and acknowledges the following packages and authors:

• phytools (Liam Revell) — phylogenetic comparative methods
• geiger (Harmon & Weir) — generalized eigenvector regression and model fitting
• corHMM (Beaulieu, O'Meara & Boyko) — hidden-rate and multi-state models
• diversitree (FitzJohn) — phylogenetic model fitting framework
• ape (Paradis & Schliep) — core phylogenetic data structures and utilities

License

GPL (>= 2)