Building phylogenetic trees with aptg

aptg builds phylogenetic trees for a list of taxa, or for a higher taxon expanded down to a lower rank. It has two backends:

library(aptg)

Trees are split by phylum

A key safeguard: aptg never builds a single tree that spans more than one phylum. There is no meaningfully calibrated deep phylogeny linking, say, land plants and vertebrates, so combining them into one tree would be misleading. Instead, taxa.tree() groups the input by phylum and returns one tree per phylum.

Here is a deliberately mixed list — three mammals and three trees:

res <- taxa.tree(c(
  "Canis lupus", "Alces alces", "Rangifer tarandus",   # phylum Chordata
  "Acer saccharum", "Acer rubrum", "Betula alleghaniensis"  # phylum Streptophyta
))

names(res$trees)
#> [1] "Chordata"     "Streptophyta"

res is a list with two components: trees (named by phylum) and unmatched (anything that could not be placed). Each element of trees is itself a list holding the phylo object and a distance matrix:

chordata <- res$trees[["Chordata"]]

chordata$tree            # an ape "phylo" object
chordata$dist            # pairwise distances among the three mammals

# Plot just the plant tree:
plot(res$trees[["Streptophyta"]]$tree)

Because Open Tree subtrees have no branch lengths, aptg assigns unit edges, so the distance matrix for the "otl" backend counts the number of edges between tips — a topological distance, not time or substitutions.

Names that Open Tree cannot resolve, that are absent from the synthetic tree, or whose lineage carries no phylum rank, are reported rather than silently dropped:

res$unmatched

Starting from a higher taxon

downto.tree() expands a taxon to all of its descendants at a chosen rank (using taxize), then feeds them to taxa.tree(). The phylum safeguard still applies, so if the descendants happen to span more than one phylum you get more than one tree back.

# Every species in the deer family:
deer <- downto.tree("Cervidae", downto = "species")
names(deer$trees)
#> [1] "Chordata"

If you hit NCBI rate limits, either supply an Entrez API key (taxize::use_entrez()) via the key argument, or switch the expansion database, e.g. downto.tree("Cervidae", "species", db = "gbif").

A dated fish tree

For ray-finned fishes, the "fish" backend gives a dated tree, which is usually what you want for comparative analyses. It requires the fishtree package:

install.packages("fishtree")  # once
fish <- taxa.tree(
  c("Thunnus thynnus", "Gadus morhua", "Danio rerio", "Salmo salar"),
  source = "fish"
)

tr <- fish$trees[["Actinopterygii"]]$tree
plot(tr)

# These branch lengths are real, so cophenetic() gives patristic (time)
# distances rather than edge counts:
fish$trees[["Actinopterygii"]]$dist

Species not in the Fish Tree of Life are dropped and listed in fish$unmatched.

Trees for a geographic area

region.tree() pulls the species of a clade recorded in an area from GBIF and builds the tree(s). Give it a required clade (taxon) plus either a radius around a coordinate or an administrative area.

# Birds within 50 km of Montreal:
region.tree("Aves", lat = 45.50, lon = -73.57, radius_km = 50)

# Mammals of a Canadian territory (all 13 provinces/territories work,
# by name or postal code):
region.tree("Mammalia", province = "Nunavut")

# Freshwater fishes of Quebec as a dated tree:
region.tree("Actinopterygii", province = "QC", source = "fish")

# Anywhere in the world via a GADM GID:
region.tree("Reptilia", gadm = "USA.5_1")

Radius mode needs geosphere; both modes need rgbif. The returned object is the usual list(trees, unmatched) plus a species element (the GBIF-derived list).

Important: GBIF gives occurrence records, not a checklist. The list is presence-only and sampling-biased — better-recorded groups and places are over-represented — so treat it as a starting point, not a definitive inventory. region.tree() counts only georeferenced records without flagged geospatial issues, but coordinate precision still varies.

Which backend should I use?

You want… Use
A tree for an arbitrary mix of taxa (any group) source = "otl" (topology)
Dated branch lengths for ray-finned fishes source = "fish"
Dated trees for other groups (birds, mammals, plants) see vignette/README notes on fishtree-style megatree packages

The "otl" backend is the general workhorse; reach for "fish" (or, in future, other clade-specific dated backends) when you need calibrated branch lengths.

References