Bio Phylo Divergence Dating

Version Compatibility

Reference examples tested with: BEAST2 2.7+, MCMCTree/PAML 4.10+, TreePL 1.0+, TempEst 1.5+, LSD2 (IQ-TREE 2.2+ --date).

Before using code patterns, verify installed versions match. If versions differ:

• CLI: beast -version, mcmctree (PAML), treePL, iqtree2 --version then the tool's -help/--help to confirm flags
• Python: pip show biopython dendropy then help(module.function) to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

BEAST2 prior-only is sampleFromPrior="true"; the MCMCTree equivalent is usedata = 0. MCMCTree calibration syntax is B()/L()/U() in the tree file, not >/<. FBD tip-dating needs the BEAST2 SA package.

Divergence Time Estimation -- A Date Is Mostly the Calibration Prior, Not the Sequence

"Estimate when these lineages diverged" -> Convert a relative rate-time tree into absolute ages using external calibrations, then report the posterior, not a point.

• CLI: BEAST2 (BEAUti XML) for full posteriors, FBD, and tip-dating
• CLI: MCMCTree (PAML) for genome-scale data via approximate likelihood
• CLI: TreePL / LSD2 for very large trees (point estimates / fast phylodynamics)

Scope: converting a rooted, branch-length tree into absolute node ages -- clock models, calibrations, dating engines, and the temporal-signal and effective-prior checks. Topology, model selection, and support -> modern-tree-inference. Posterior distributions, MCMC convergence, and site-heterogeneous models -> bayesian-inference. The clock-based rooting concept and re-rooting -> tree-manipulation. Reading/writing the dated MCC tree without dropping HPD intervals -> tree-io. Phylodynamic population-size / Re estimation -> epidemiological-genomics/phylodynamics.

The Single Most Important Modern Insight

A divergence date is a product of the calibration priors and the clock model far more than of the sequence data. A branch length is the product b = rate x time (expected substitutions per site); the likelihood depends on b alone, so the pair (rate, time) is nonidentifiable -- doubling every rate and halving every time leaves the likelihood unchanged. Sequences therefore carry information about the relative rate-time tree only, and calibrations are the one thing that converts it to absolute millions of years. The posterior on a node age is consequently dominated by the (often subjective) calibration prior and by how the tree prior and neighboring calibrations reshape it. Three load-bearing facts:

1. More sequence data does not escape the calibration. Adding genes sharpens the relative tree but the residual uncertainty in node ages is bounded below by calibration uncertainty; a precise posterior on a badly placed fossil is a precise estimate of the wrong age (dos Reis and Yang 2011; see the infinite-sites plot below).
2. The honest practice is to run the MCMC sampling from the prior (no data) and report the effective prior. Topological ordering and neighboring calibrations truncate each specified density, so the marginal (effective) prior the model actually uses is generically NOT the density typed in (Heled and Drummond 2012; Warnock et al. 2012). Report three numbers per calibrated node: specified prior, effective prior, posterior.
3. A tight credible interval is not evidence the data nailed the age. If the posterior coincides with the effective prior, the data added nothing and the prior is being reported back; tightness usually traces to a tight (or mutually truncating) prior, not to the molecular signal (Brown and Smith 2018).

Clock Model Selection

The clock governs how substitution rate varies across branches; choosing it wrong biases dates and misstates their uncertainty. Choose by testing clocklikeness, not by defaulting either way.

Relaxed-clock work was established by Drummond et al. 2006 (uncorrelated relaxed clocks, "dating with confidence"). The single most useful BEAST2 relaxed-clock diagnostic is the coefficient of variation (CoV) of branch rates, derived from ucld.stdev: a CoV posterior abutting 0 (ucld.stdev near 0) means rates are effectively constant and a strict clock suffices (gain precision by simplifying); a CoV clearly above 0 with 0 excluded means the relaxed clock is doing necessary work and a strict clock would be falsely precise. If the ucld.stdev posterior just recovers its prior, the data cannot indicate how clocklike the lineages are -- report that. Use the CoV for a quick read, but decide strict-vs-relaxed formally by marginal-likelihood comparison (path sampling / stepping-stone).

Calibration Strategy

Calibrations are the dominant input. The bedrock rule: a fossil is a MINIMUM, not a point -- a clade is at least as old as a fossil assigned to it, and the true divergence is older, so a near-delta prior on a fossil age forces a guaranteed-too-young, falsely precise node.

Soft bounds (Yang and Rannala 2006) make a bound a quantile, not a wall: a small canonical 0.025 tail of probability is allowed beyond each soft min/max so one bad fossil cannot dominate. Justify every fossil per Parham et al. 2012 (specimen identity, apomorphy-based placement, geochronologic basis, monophyly of the calibration clade, stated reasoning). The total-evidence approach (Ronquist et al. 2012) includes fossils as dated tips scored for morphology so the data, not the user, place each fossil. The fossilized birth-death process (Heath et al. 2014) is the modern coherent tree prior: it models speciation, extinction, and fossil sampling jointly, uses ALL fossils, allows sampled ancestors, and replaces the incoherent practice of multiplying ad hoc node densities. Prefer FBD when several fossils exist; use simple node densities only for one or two transparent constraints. Secondary calibrations (an age borrowed from another study) launder uncertainty -- never use a point, use the full distribution, and flag it.

Tool Taxonomy

MCMCTree's approximate likelihood does the expensive Felsenstein pruning once (computing branch-length MLEs, gradient, and Hessian per partition) rather than every MCMC step, which is what makes thousands of loci tractable; check that BASEML converged because unreliable per-partition branch lengths (saturated/short loci) corrupt the approximation. The infinite-sites plot (dos Reis and Yang 2011) plots posterior CI width against posterior mean age across nodes: under infinite data the relationship becomes linear through the origin, with the residual width set entirely by calibration uncertainty -- if real-data points already hug that line, more sequence data will NOT narrow the dates and the answer is better fossils, not more sites. TreePL and r8s return one number per node and produce NO uncertainty; a bare PL date is a failure mode, not a result -- bootstrap for CIs and cross-validate lambda.

Temporal Signal Before Tip-Dating

When samples are collected at different times and the population evolves fast enough to accumulate measurable substitutions between dates (a measurably-evolving population: viruses, ancient DNA), the sampling-date differences themselves are the calibrations -- no fossil needed. Verifying temporal signal first is non-negotiable; a short-time-span dataset frequently has no signal yet a Bayesian run will return a tight, entirely prior-driven date.

• Root-to-tip regression (TempEst, Rambaut et al. 2016): build a rough ML tree, regress each tip's root-to-tip genetic distance against its sampling date. A genuine signal gives a positive slope (the slope estimates the rate); a negative slope means no usable signal or a wrong root. R^2 is exploratory only (tips are non-independent): treat near-zero / much-below ~0.2 as a red flag, not a formal pass. The x-intercept estimates the TMRCA as a sanity check; large-residual tips are date/contamination/recombination outliers to investigate before dating.
• Date-randomization test (Duchene et al. 2015): the formal test. Re-run the dating with tip dates shuffled many times; the real-data clock-rate estimate must fall OUTSIDE the distribution of randomized replicates (no CI overlap). If the real estimate sits inside that cloud, there is no temporal signal and any date is an artifact of the prior.

Run Prior-Only to Expose the Effective Prior

Goal: Determine whether the molecular data inform each calibrated node, or whether the reported posterior is just a truncated prior reflected back.

Approach: Run the same model first with no sequence data to obtain the effective (marginal) prior, then with data; compare specified-vs-effective-vs-posterior on every calibrated node.

# BEAST2: edit the XML so the MCMC samples from the prior only (no likelihood)
# set <run ... sampleFromPrior="true"> (BEAUti: MCMC panel, "Sample From Prior")
beast -seed 1 -prefix prioronly prioronly.xml      # effective prior on every node
beast -seed 1 -prefix withdata  withdata.xml       # full posterior

# MCMCTree: usedata=0 gives the effective prior; usedata=2 the approx-likelihood posterior
mcmctree mcmctree_prior.ctl    # control file has usedata = 0
mcmctree mcmctree_post.ctl     # control file has usedata = 2

from Bio import Phylo

prior = Phylo.read('prioronly.mcc.tree', 'nexus')   # effective prior summary
post = Phylo.read('withdata.mcc.tree', 'nexus')      # posterior summary
for c_prior, c_post in zip(prior.get_nonterminals(), post.get_nonterminals()):
    # if the posterior median and HPD ~ the effective prior, the data did not inform this node
    print(c_prior.confidence, c_post.confidence)     # compare per-node summaries side by side

Check Temporal Signal Before Tip-Dating

Goal: Confirm a heterochronous (virus / ancient-DNA) dataset actually contains clock signal before committing to a Bayesian tip-dated run.

Approach: Regress root-to-tip distance on sampling date (positive slope, sane intercept, outliers flagged), then run a date-randomization test; only date if the real estimate sits outside the randomized cloud.

# Build a quick ML tree to feed TempEst (modern-tree-inference)
iqtree2 -s seqs.fa -m GTR+G -T AUTO --prefix rttree
# TempEst (GUI): load rttree.treefile + a tab file of tip sampling dates;
# read the root-to-tip regression -- require a POSITIVE slope; inspect R^2 and residual outliers.

# Fast non-Bayesian tip-dating + CI as a cross-check (LSD2 via IQ-TREE)
iqtree2 -s seqs.fa -m GTR+G --date dates.tsv --date-ci 100 --prefix lsd2   # dates.tsv: tip <tab> date

Per-Method Failure Modes