Tutorial 6: Testing for phylogenetic signal in continuous traits

Objectives

  • Complete the testing for phylogenetic signal in continuous traits workflow.

  • Interpret the reported values and generated artifacts in their scientific context.

  • Identify the canonical command references for each analysis step.

Prerequisites and working directory

Install the current PhyKIT release and create a dedicated working directory. Download the data linked in this tutorial into that directory before running the commands. All paths below are relative to this directory.

mkdir phykit-tutorial-06
cd phykit-tutorial-06

Workflow

A fundamental question in comparative biology is whether closely related species resemble each other more than expected by chance — a pattern known as phylogenetic signal (Blomberg et al. 2003; Pagel 1999). Quantifying phylogenetic signal helps determine whether phylogenetic comparative methods (e.g., PGLS, phylogenetic PCA) are necessary for a given trait, and provides insight into the evolutionary processes shaping trait variation (Münkemüller et al. 2012).

Hypothetical study question. Suppose we are studying body mass evolution across eight mammal species and want to know: does body mass exhibit significant phylogenetic signal? In other words, do closely related species tend to have more similar body masses than species drawn at random from the tree?

PhyKIT's phylogenetic_signal command (aliases: phylo_signal, ps) implements two widely used measures: Blomberg's K and Pagel's lambda.

In this tutorial, we will use the test data included with PhyKIT: an eight-taxon mammal phylogeny and a tab-delimited trait file containing log-transformed body mass values.

Download test data: Mammal phylogeny; Continuous trait data


Step 0: Prepare data

Two input files are needed: a phylogenetic tree in Newick format and a tab-delimited trait file with two columns (taxon name and trait value). Lines starting with # are treated as comments. The trait file looks like this:

# Trait data for tree_simple.tre taxa
# body mass (kg, log-transformed)
raccoon      1.04
bear 2.39
sea_lion     2.30
seal 1.88
monkey       0.60
cat  0.56
weasel       -0.30
dog  1.18

Download both files above into the tutorial working directory.


Step 1: Calculate Blomberg's K

Blomberg's K compares the observed trait variance partitioned across the phylogeny to the expectation under Brownian motion. K = 1 indicates trait evolution consistent with Brownian motion; K < 1 suggests less phylogenetic signal than expected (e.g., convergent evolution); K > 1 suggests stronger signal than expected (e.g., trait conservatism within clades).

Statistical significance is assessed via a permutation test that shuffles trait values among tips.

phykit phylogenetic_signal \
    -t tree_simple.tre \
    -d tree_simple_traits.tsv

0.5842       0.474   0.9499

col1: Blomberg's K statistic
col2: p-value (permutation test, 1000 permutations)
col3: R²_phylo, the relative reduction in fitted variance under Brownian motion compared with a white-noise model

Interpretation. K = 0.58 (< 1), suggesting that body mass shows less phylogenetic signal than expected under pure Brownian motion in this clade. The p-value of 0.47 is non-significant, meaning we cannot reject the null hypothesis that there is no phylogenetic signal. With only 8 taxa, statistical power is limited, so this result should be interpreted cautiously. R²_phylo = 0.95 describes the variance-model comparison; it is not an estimate of Pagel's lambda or a literal percentage of variance caused by phylogeny.


Step 2: Calculate Pagel's lambda

Pagel's lambda scales the off-diagonal elements of the phylogenetic variance-covariance matrix. Lambda = 1 indicates strong phylogenetic signal (consistent with Brownian motion); lambda = 0 indicates no phylogenetic signal (traits evolve independently of phylogeny). Significance is assessed via a likelihood ratio test comparing the fitted lambda model to a model with lambda fixed at 0.

phykit phylogenetic_signal \
    -t tree_simple.tre \
    -d tree_simple_traits.tsv \
    -m lambda

1.0  -11.5697        0.7165  0.9499

col1: estimated lambda
col2: log-likelihood of the fitted model
col3: p-value (likelihood ratio test)
col4: R²_phylo

Interpretation. Lambda = 1.0 indicates a maximum-likelihood estimate consistent with Brownian motion. However, the LRT p-value of 0.72 is non-significant, meaning the fitted model does not significantly improve over the null (lambda = 0). Again, with 8 taxa, power is limited.


Step 3: Export results as JSON

For scripting or downstream analysis, use --json:

phykit phylogenetic_signal \
    -t tree_simple.tre \
    -d tree_simple_traits.tsv \
    --json

{"K": 0.584216001752301, "p_value": 0.474, "permutations": 1000, "r_squared_phylo": 0.9499081827368852}

phykit phylogenetic_signal \
    -t tree_simple.tre \
    -d tree_simple_traits.tsv \
    -m lambda \
    --json

{"lambda": 0.9999933893038647, "log_likelihood": -11.569678737014614, "p_value": 0.7165426341460481, "r_squared_phylo": 0.9499081827368852}

Summary

In this tutorial, we used two measures of phylogenetic signal — Blomberg's K and Pagel's lambda — to assess whether body mass evolution in a mammal clade is structured by phylogenetic relationships. Both measures can help researchers decide whether phylogenetic comparative methods are needed for their data and provide insight into the tempo and mode of trait evolution.

For methodological details, see Blomberg et al. (2003) and Pagel (1999). The R equivalent is phytools::phylosig() (Revell 2012).


Expected artifacts

Each step identifies its expected terminal output or generated files. Confirm that those artifacts exist before continuing to the next step; filenames are relative to the tutorial working directory unless an absolute path is shown.

Troubleshooting

  • Run phykit <command> --help to compare an invocation with the live interface.

  • Confirm that downloaded files are in the current working directory and retain the filenames shown in the tutorial.

  • For parsing errors, compare taxon names exactly across alignments, trees, and trait tables, including capitalization and underscores.

  • See Troubleshooting for installation, format, and error-reporting guidance.