extractTree: Extract a complete or pre-pruned phylogeny from the clootl...

In clootl: Fetch and Explore the Cornell Lab of Ornithology Open Tree of Life Avian Phylogeny

Extract a complete or pre-pruned phylogeny from the clootl datastore

Description

This function extracts one or more phylogenies in the desired taxonomy and tree version. It defaults to the pre-packaged summary trees, but can also be used to extract sets of phylogenies expressing uncertainty, once they have been downloaded from the online repository.

Usage

extractTree(
  species = "all_species",
  label_type = "scientific",
  taxonomy_year = 2025,
  version = "1.6",
  data_path = FALSE,
  force = FALSE
)

Arguments

species	A character vector either of scientific names (directly as they come out of the eBird taxonomy, i.e. without underscores) or of six-letter eBird species codes. Any elements of the species vector that do not match a species-level taxon in the specified eBird taxonomy will result in an error. eBird taxonomy files can be accessed using taxonomyGet(). Default is set to "all_species".
label_type	Either "scientific" or "code". Default is set to "scientific".
taxonomy_year	The eBird taxonomy year the tree should be output in. Current options are 2021-2024. Both numeric and character inputs are acceptable here. Any value aside from these years will result in an error. Default is most recent year.
version	The desired version of the tree. Default to the most recent version of the tree. Other versions available are listed in clootl_data$versions and can be passed as a character string or as numeric.
data_path	Default to FALSE. If a summary, dated tree is desired, this is sufficient and does not need to be modified. However, if a user wishes to extract a set of complete dated trees, for example to iterate an analysis across a cloud of trees, or to use an older version of the tree than the current one packed in the data object, this function can also accept a path to the downloaded set of trees. If you have already downloaded the AvesData repo available at https://github.com/McTavishLab/AvesData use data_path= the path to the download location. Alternately, you can download the full data repo using get_avesdata_repo(). This approach will download the data and set an environmental variable AVESDATA_PATH. When AVESDATA_PATH is set, the data_path will default to this value. To manually set AVESDATA_PATH to the location of your downloaded AvesData repo use set_avesdata_repo_path()
force	Default to FALSE. If FALSE a tree will be returned only if there is an exact match in the tree to all species requested. This function first ensures that the requested output species overlap with species-level taxa in the requested eBird taxonomy. If they do not, the function will error out. The onus is on the user to ensure the requested taxa are valid. This is critical to ensure no unexpected analysis hiccups later–you don't want to find out many steps later that your dataset doesn't match your phylogeny. If force=TRUE even if there is is not a match to all taxa in the requested species list, a tree will be returned for the species that do match.

Value

One or more phylogenies of the specified taxa in the specified eBird taxonomy version and clootl tree version.

Author(s)

Eliot Miller, Luna Sanchez Reyes, Emily Jane McTavish

Examples

ex1 <- extractTree(species=c("amerob", "canwar", "reevir1", "yerwar", "gockin"),
   label_type="code")
ex2 <- extractTree(species=c("Turdus migratorius",
                             "Setophaga dominica",
                             "Setophaga ruticilla",
                             "Sitta canadensis"),
   label_type="scientific",
   taxonomy_year="2025",
   version="1.6")

clootl documentation built on April 24, 2026, 1:07 a.m.