Get a phylogeny from the Fish Tree of Life

Retrieves a phylogeny via the Fish Tree of Life API. If neither `species` nor `taxon` are specified, returns the entire phylogeny.

Usage

fishtree_phylogeny(
  species,
  taxon,
  type = c("chronogram", "phylogram", "chronogram_mrca", "phylogram_mrca"),
  release = getOption("fishtree.release", .default_release),
  rank = deprecated()
)

Arguments

species: (Optionally) subset the results based on a vector of species names.
taxon: (Optionally) subset the results to the taxon with this name, such as a family or order (e.g., `"Acanthuridae"`).
type: Either `"chronogram"` or `"phylogram"`. A chronogram has branch lengths proportional to units of time, while a phylogram has branch lengths proportional to the amount of character change. When retrieving a phylogeny for a taxon that is not recovered as monophyletic, acceptable types also include `"chronogram_mrca"` and `"phylogram_mrca"`, which returns a tree with *all* species descending from the common ancestor of species in the taxon.
release: The tree release to use, from fishtree_releases. Defaults to `getOption("fishtree.release")`, or `"R2018"` if that is unset. Looking up a `taxon` is only available for `"R2018"`.
rank: Deprecated; use `taxon` instead.

Value

An object of class `"phylo"`.

Details

For maximum interoperability, `species` considers spaces and underscores equivalently. Internally, the phylogenies use underscores.

References

Rabosky, D. L., Chang, J., Title, P. O., Cowman, P. F., Sallan, L., Friedman, M., Kashner, K., Garilao, C., Near, T. J., Coll, M., Alfaro, M. E. (2018). An inverse latitudinal gradient in speciation rate for marine fishes. Nature, 559(7714), 392–395. doi:10.1038/s41586-018-0273-1

Examples

if (FALSE) { # \dontrun{
# Get a phylogeny for a taxon
surgeons <- fishtree_phylogeny(taxon = "Acanthuridae")

# Get a phylogeny for only certain species
genomic_fish <- c("Oryzias latipes", "Tetraodon nigroviridis",
                  "Gasterosteus aculeatus", "Danio rerio")
fishtree_phylogeny(species = genomic_fish)

# Chronograms may not be ultrametric due to numerical precision issues
# Consider using phytools::force.ultrametric
ape::is.ultrametric(surgeons)
ape::is.ultrametric(surgeons, tol = 0.00001)

# Difference between MRCA trees and regular trees
gobies_mrca <- fishtree_phylogeny(taxon = "Gobiidae", type = "chronogram_mrca")
gobies <- fishtree_phylogeny(taxon = "Gobiidae", type = "chronogram")
# MRCA trees will have more tips for non-monophyletic groups
length(gobies_mrca$tip.label) > length(gobies$tip.label)
# Drop rogue tips in the MRCA tree
rogue_gobies <- fishtree_rogues("Gobiidae")
pruned_gobies <- ape::drop.tip(gobies_mrca, rogue_gobies)
# Now the trees are identical
setequal(gobies$tip.label, pruned_gobies$tip.label)
} # }