fastphylosig

fastphylosig · R package · v0.3.5

Fast phylogenetic signal analysis in R

At 2,000 tips, fastphylosig computes phylogenetic signal up to 23,591× faster.

Phylogenetic signal measures how similar a trait is among closely related species. fast_signal() computes K, lambda, D or Delta in one call, and the speed advantage grows with tree size (see the benchmark). fast_hetero() compares signal among clades within a large tree (see the 512-species case study).

Blomberg's K

135–151×

at 2,000 tips

Pagel's lambda

20,697–23,591×

at 2,000 tips

Fritz–Purvis D

218–224×

at 2,000 tips

Categorical Delta

23.9–33.6×

at 2,000 tips

Ratios are reference median time ÷ fastphylosig median time, so a value above 1 means fastphylosig was faster. The references are phytools 2.5.2 for K and lambda, caper for D, and the published Borges (2019) code for Delta. Each range covers three designed signal scenarios (Brownian/noise mixtures with weights 0, 0.5 and 0.95).

Install and get started

Install v0.3.5

The v0.3.5 release is the latest version. It provides the full clade-scale workflow and improves D/lambda performance.

install.packages(
  "https://github.com/yinwen-ecology/fastphylosig/releases/download/v0.3.5/fastphylosig_0.3.5.tar.gz",
  repos = NULL, type = "source"
)
library(fastphylosig)

Source installation needs a C++17 toolchain and, on Windows, Rtools. It also requires ape, Rcpp and RcppArmadillo.

One call for K, lambda, D or Delta

Simulated example data

set.seed(1)
tree <- ape::rtree(30)
trait <- setNames(stats::rnorm(30), tree$tip.label)
binary <- setNames(as.integer(trait > stats::median(trait)), tree$tip.label)
state <- setNames(sample(letters[1:3], 30, replace = TRUE), tree$tip.label)

K

k <- fast_signal(tree, data = trait, method = "K",
                 test = TRUE, nsim = 999,
                 return_sim = TRUE, progress = FALSE)

lambda

lambda <- fast_signal(tree, data = trait, method = "lambda",
                      test = TRUE, progress = FALSE)

D

d <- fast_signal(tree, data = binary, method = "D",
                 test = TRUE, nsim = 999,
                 return_sim = TRUE, progress = FALSE)

Delta

delta <- fast_signal(tree, data = state, method = "Delta",
                     test = TRUE, nsim = 199, progress = FALSE)

Technical workflow

fast_signal() combines tree checking, tree–trait matching, missing-value handling and signal calculation. If needed, the four steps can also be run separately.

Workflow diagram: the high-level fast_signal route performs checks, tree preparation, data matching, and method dispatch; an advanced route exposes each preparation step before calling a method-specific function.
Open the SVG for the full-size diagram.
Run the four steps separately 
checked <- check_tree(tree, signal = "K")
tree_ready <- resolve_tree(tree, signal = "K")
matched <- match_tree_data(tree_ready, data = trait)
ctx <- prepare_tree(matched$tree)

k <- fast_k(ctx, x = matched$data, test = TRUE, nsim = 999,
            progress = FALSE)

See the Chinese usage guide and the complete v0.3.0 examples.

Runtime against the standard implementations

K and lambda are compared with phytools 2.5.2 phylosig(), D with caper 1.0.4 phylo.d(), and Delta with the published Borges (2019) code. Trees of 50 to 2,000 tips, three signal scenarios, and 10 paired replicates per setting (20 timed calls). Timing starts after tree and data preparation.

Four aligned panels compare reference-to-fastphylosig runtime ratios for K, lambda, D, and Delta at 50, 100, 500, and 2,000 tips. A dashed horizontal line marks equal runtime; ratios below it mean the standard implementation was faster.
Measured runtime by statistic and tree size. The dashed line marks equal median runtime; ratios below it mean the standard implementation was faster. Click the figure to open the full-size PNG. Results are from Windows 11 x64 with R 4.6.1; setup and tree/data preparation were excluded.

plot_signal

Plots from simulated data.

Native plot_signal output showing K permutation distributions for multiple traits.
K across traitsPermutation distributions with observed-value markers.
Native plot_signal output showing a Pagel lambda likelihood profile.
Pagel's lambdaLikelihood profile and estimate.
Two native plot_signal panels showing D calibrations against random and Brownian null distributions.
Fritz–Purvis DRandom and Brownian null views.
Delta permutation demo showing the permuted distribution and the observed Delta marked by a vertical line.
DeltaPermutation distribution and observed value.

View all six plot styles and the Delta demo

Compare clades within a large tree with fast_hetero()

In a large tree (say more than 1,000 tips), a single signal value cannot describe how lineages differ: some clades may be more conserved, others more labile. I developed fast_hetero() to split the tree into crown clades (a node and all its descendants), estimate signal for each, and set the local estimates beside the whole-tree value. You can name the clades yourself, or let the function choose the largest non-overlapping clades within a size range. Results keep the real sample size of each clade, its missing observations, its state composition and its fit and MCMC diagnostics.

fast_hetero technical workflow, from tree compilation and crown selection through shared C++ kernels to local and whole-tree results, optional reference tests and native plots.
fast_hetero() workflow: select crowns, reuse the method kernels, then combine local estimates, optional whole-tree analysis and diagnostics. Follow the workflow in the case study · 中文路线图

Demonstration case

Native fast_hetero tree plot for eight selected crowns in a simulated 512-species tree, with whole-tree K, its ordinary signal P and a separate BM dispersion P.
Built-in plot() output from the case study; numbers, diagnostics, code and data are on the case page.

Read the full case study

Other notes

Delta diagnostics

Delta ratios compare returned calls, not accuracy. The reference emitted numerical warnings in 112 of 120 calls and exposes no final convergence check, and one fast call reached its optimizer limit. No warned call was removed or re-run, so these ratios do not show that the two implementations are equally accurate or equally converged. Warnings are retained in the raw timed-call records, with counts by type in the benchmark QA report.

The current release is fastphylosig v0.3.5. The runtime figures above come from v0.3.0 and were not re-run for v0.3.4, because the core computational code did not change. See the release notes and the fast_hetero case study.

Source codeReport an issueBenchmark and usage details