Time-calibrate a topology using the DateLife chronogram database

Wraps datelife::datelife_use() to add divergence-time calibrations to an existing phylo (or multiPhylo) using DateLife's database of pre-computed chronograms (Sanchez Reyes et al. 2024, Systematic Biology 73:470). Returns a result with the same shape as pr_get_tree() so downstream PCM workflows — including pigauto's posterior-tree imputation — can consume it without further glue code.

Usage

pr_date_tree(
  tree,
  n_dated = 1L,
  dating_method = "bladj",
  check_ultrametric = TRUE,
  ...
)

Arguments

tree

An ape::phylo (or multiPhylo) object: the topology (or topologies) to calibrate.

n_dated

A length-1 positive integer. How many calibrated trees to return per input topology. 1L (default) returns a single dated tree (DateLife's combined SDM-summary chronogram); > 1L triggers each = TRUE so DateLife returns one chronogram per source paper in its database (capped at n_dated). All resulting chronograms share the input topology — only the branch lengths vary across the returned set.

dating_method

A length-1 character vector. Forwarded to datelife::datelife_use(). One of "bladj" (default; fast, no calibration uncertainty) or "mrbayes" (Bayesian; slower, produces credible intervals).

check_ultrametric

Logical. After dating, check that the result is ultrametric and warn if not. Default TRUE. datelife::datelife_use() is supposed to produce ultrametric chronograms; this catches regressions.

...

Additional arguments forwarded to datelife::datelife_use().

Value

A list with class pr_tree_result and components:

tree

The dated topology — a phylo when n_dated = 1 or a multiPhylo when n_dated > 1.

matched

Tip labels of the input that DateLife was able to date.

unmatched

Tip labels of the input absent from DateLife's database (returned with no calibration applied).

mapping

A tibble with one row per input tip label, mirroring pr_get_tree()'s audit table: input_name, normalized_name, query_name, tree_name, in_tree, match_type, placement_status, and the four tnrs_* columns. placement_status and the tnrs_* columns are NA for DateLife dating, which applies no TNRS step.

source

Always "datelife" (paired with pr_get_tree()'s dispatch).

backend_meta

Includes dating_method, calibrations (per-node calibration table from DateLife), and the standard tree_provenance list (one entry per returned tree).

When to use this

Use pr_date_tree() when you already have a topology (e.g. from a published phylogeny or your own analysis) and want to attach divergence times. Use pr_get_tree() with source = "datelife" if you have only species names. Both end up calling the GitHub-only datelife package, but the starting point is different. Install datelife before calling this function — prepR4pcm does NOT pull it in via Suggests (its transitive dep tree can't be auto-resolved by pak on a clean CI image, so we keep it as an opt-in install): pak::pak("phylotastic/datelife").

What "n_dated > 1" actually returns

This is a common point of confusion. With n_dated = 50, pr_date_tree() does NOT change the input topology — it returns up to 50 chronograms that all share the input topology but differ in their branch lengths, because each variant is dated using a different source paper in DateLife's chronogram database (think: variant 1 uses Hedges et al. 2015, variant 2 uses Bininda-Emonds et al. 2007, etc.). So you get one topology and N versions of branch lengths, not N different topologies.

If you want both axes of variation (topology uncertainty + dating uncertainty), feed a multiPhylo of N topologies in. DateLife's each = TRUE mode is then applied per input tree, so the output reflects the cross-product of input topology and DateLife source. Example pipeline:

  trees  <- pr_get_tree(species, source = "rtrees",
                         taxon = "mammal")  # ~100 topologies
  dated  <- pr_date_tree(trees$tree, n_dated = 5)

By contrast, pr_get_tree(species, source = "datelife", n_tree = 50) returns up to 50 chronograms where each variant comes from a different DateLife source — i.e. a different topology AND different branch lengths per variant, because DateLife's source chronograms aren't constrained to share a topology.

References

Sanchez Reyes, L. L., McTavish, E. J., & O'Meara, B. (2024). DateLife: Leveraging databases and analytical tools to reveal the dated Tree of Life. Systematic Biology, 73(2), 470–485. doi:10.1093/sysbio/syae015

See also

pr_get_tree() for retrieval (species –> tree); pr_cite_tree() for formatting the citations of the result; reconcile_augment() for filling tip-level gaps in an existing tree (a complementary operation to dating).

Examples

# \donttest{
  if (rlang::is_installed("datelife")) {
    # Example 1: one chronogram from a topology
    library(ape)
    tr  <- read.tree(text =
      "(Rhea_americana,(Pterocnemia_pennata,Struthio_camelus));")
    res <- pr_date_tree(tr)
    res$tree                       # phylo (chronogram)
    res$backend_meta$dating_method # "bladj"

    # Example 2: per-source chronograms for posterior-tree PCMs
    res <- pr_date_tree(tr, n_dated = 5)
    class(res$tree)                # "multiPhylo"
    length(res$backend_meta$tree_provenance)  # one entry per tree
  }
# }