Type: Package
Title: Interface to the Fish Tree of Life API
Version: 0.3.4
Description: An interface to the Fish Tree of Life API to download taxonomies, phylogenies, fossil calibrations, and diversification rate information for ray-finned fishes.
License: BSD_2_clause + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.1.1
URL: https://fishtreeoflife.org/, https://github.com/jonchang/fishtree
BugReports: https://github.com/jonchang/fishtree/issues
Depends: R (≥ 4.0)
Imports: ape (≥ 5.2), jsonlite (≥ 1.5), memoise, parallel, rlang (≥ 0.4.1), utils
Suggests: diversitree, geiger, hisse (≥ 1.9.10), knitr, markdown, phytools, picante, rfishbase, rmarkdown, spelling, testthat
VignetteBuilder: knitr
Language: en-US
NeedsCompilation: no
Packaged: 2021-01-28 04:06:30 UTC; jonchang
Author: Jonathan Chang ORCID iD [aut, cre], Michael E Alfaro [ctb], Daniel L Rabosky [ctb], Stephen A Smith [ctb]
Maintainer: Jonathan Chang <me@jonathanchang.org>
Repository: CRAN
Date/Publication: 2021-01-31 00:50:06 UTC

fishtree: Interface to the Fish Tree of Life API

Description

fishtree makes it easy to access phylogenetic information about ray-finned fishes with R. Download taxonomies, phylogenies, sequence matrices, and diversification rate data with a simple set of functions.

Details

Implementation note: this package makes calls over the network and caches its (sometimes large) results for faster loading. Because of this, long-running R instances could use a lot of memory.

Author(s)

Maintainer: Jonathan Chang me@jonathanchang.org (ORCID)

Other contributors:

See Also

Useful links:

Get aligned sequences from the Fish Tree of Life

Description

Retrieves an aligned sequence via the Fish Tree of Life API. If neither 'species' nor 'rank' are specified, returns the entire sequence matrix.

Usage

fishtree_alignment(species, rank, split = FALSE)

Arguments

species

(Optionally) subset the results based on a vector of species names.

rank

(Optionally) subset the results based on the supplied taxonomic rank.

split

Splits the output into a list by gene locus.

Value

An object of class '"DNAbin"', or a named list of the same if 'split = TRUE“

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

See Also

DNAbin

Examples

## Not run: 
surgeon_dna <- fishtree_alignment(rank = "Acanthuridae", split = TRUE)
surgeon_dna[[1]]
par(mfrow = c(9, 3), mar = c(0.5, 0.5, 1, 0.5), xaxt = "n", yaxt = "n")
for (gene in names(surgeon_dna)) {
  image(surgeon_dna[[gene]], legend = FALSE, show.labels = FALSE)
  title(gene)
}

## End(Not run)

Get complete (stochastically-resolved) phylogenies from the Fish Tree of Life

Description

Retrieves a complete phylogeny generated by stochastic polytomy resolution via the Fish Tree of Life API. If neither 'species' nor 'rank' are specified, returns the entire phylogeny. See Rabosky et al. (2018) and Chang et al. (2019) for details on how these phylogenies were built using stochastic polytomy resolution. WARNING: These phylogenies should generally not be used for downstream analyses of trait evolution. See Rabosky (2015) for details.

Usage

fishtree_complete_phylogeny(
  species,
  rank,
  mc.cores = getOption("mc.cores", 1L)
)

Arguments

species

(Optionally) subset the results based on a vector of species names.

rank

(Optionally) subset the results based on the supplied taxonomic rank.

mc.cores

Number of cores to use in mclapply when subsetting the tree (default '1')

Value

An object of class '"multiPhylo"' that should probably not be used for analyses of trait evolution, including (but not limited to) pic, ace, corBrownian, make.bisse, or hisse.

References

Rabosky, D. L. (2015). No substitute for real data: A cautionary note on the use of phylogenies from birth-death polytomy resolvers for downstream comparative analyses. Evolution, 69(12), 3207–3216. doi:10.1111/evo.12817

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

Chang, J., Rabosky, D. L., & Alfaro, M. E. (2019). Estimating diversification rates on incompletely-sampled phylogenies: theoretical concerns and practical solutions. Systematic Biology. doi:10.1093/sysbio/syz081

Enhanced polytomy resolution strengthens evidence for global gradient in speciation rate for marine fishes. https://fishtreeoflife.org/rabosky-et-al-2018-update/

Examples

## Not run: 
tree <- fishtree_complete_phylogeny(rank = "Acanthuridae")
sampled_tips <- fishtree_phylogeny(rank = "Acanthuridae")$tip.label
all_tips <- tree[[1]]$tip.label
new_tips <- setdiff(all_tips, sampled_tips)
par(mfrow = c(2,2))
for (ii in 1:4) {
  plot(tree[[ii]], show.tip.label = FALSE, no.margin = TRUE)
  ape::tiplabels(pch = 19, col = ifelse(tree[[ii]]$tip.label %in% new_tips, "red", NA))
}

## End(Not run)

Get a phylogeny from the Fish Tree of Life

Description

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

Usage

fishtree_phylogeny(
  species,
  rank,
  type = c("chronogram", "phylogram", "chronogram_mrca", "phylogram_mrca")
)

Arguments

species

(Optionally) subset the results based on a vector of species names.

rank

(Optionally) subset the results based on the supplied taxonomic rank.

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 by rank, and that rank 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 specified rank.

Details

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

Value

An object of class '"phylo"'.

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

See Also

fishtree_rogues, read.tree, force.ultrametric

Examples

## Not run: 
# Get a phylogeny for a taxonomic rank
surgeons <- fishtree_phylogeny(rank = "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(rank = "Gobiidae", type = "chronogram_mrca")
gobies <- fishtree_phylogeny(rank = "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)

## End(Not run)

Get rogue taxa that break the monophyly of defined taxa

Description

For groups that were recovered as paraphyletic in the phylogenetic analysis, uses the Fish Tree of Life API to identify which species prevented that clade from being recovered as monophyletic.

Usage

fishtree_rogues(rank)

Arguments

rank

the (possibly paraphyletic) rank for which rogue or intruder species should be identified.

Value

A vector of species names, potentially empty.

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

## Not run: 
fishtree_rogues("Gobiidae")   # several rogue taxa!
fishtree_rogues("Labridae")   # nice and monophlyetic

## End(Not run)

Get taxonomies and other data from the Fish Tree of Life

Description

Retrieves taxonomic and other information from the Fish Tree of Life API.

Usage

fishtree_taxonomy(ranks = NULL)

Arguments

ranks

One or more taxonomic ranks to retrieve.

Value

A list, with components containing data on the specified taxa. If 'ranks' is unspecified, a data frame with all valid taxa is returned instead.

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

## Not run: 
tax <- fishtree_taxonomy(rank = "Labridae")
n_total <- length(tax$Labridae$species)
n_sampl <- length(tax$Labridae$sampled_species)
paste("There are", n_sampl, "sampled species out of", n_total, "in wrasses.")

## End(Not run)

Get tip rates for the Fish Tree of Life

Description

Downloads tip rates for the entire Fish Tree of Life, or for a specified subset. Tip rates can be thought of as an instantaneous speciation or extinction rate; for example, a higher tip-specific speciation rate might imply that a lineage is more likely to split a new lineage at the present time. See Title (2019) in references for details. If neither 'species' nor 'rank' are specified, returns the entire set of tip-specific diversification rates.

Usage

fishtree_tip_rates(species, rank, sampled_only = TRUE)

Arguments

species

(Optionally) subset the results based on a vector of species names.

rank

(Optionally) subset the results based on the supplied taxonomic rank.

sampled_only

Restricts the returned dataset to only those species that have genetic data available. Defaults to 'TRUE'.

Value

A data frame. Columns ending with '.tv' indicate time-variable BAMM runs; those ending in '.tc' are time-constant runs. The 'dr' column refers to the DR statistic, while 'lambda' and 'mu' are speciation and extinction, respectively.

References

DR rates (supplement, section 1.2.2): Jetz, W., Thomas, G. H., Joy, J. B., Hartmann, K., & Mooers, A. O. (2012). The global diversity of birds in space and time. Nature, 491(7424), 444–448. doi:10.1038/nature11631

Interpreting tip rates: Title, P. O., & Rabosky, D. L. (2019). Tip rates, phylogenies and diversification: What are we estimating, and how good are the estimates? Methods in Ecology and Evolution, 10(6), 821–834. doi:10.1111/2041-210x.13153

BAMM rates: Rabosky, D. L. (2014). Automatic Detection of Key Innovations, Rate Shifts, and Diversity-Dependence on Phylogenetic Trees. PLoS ONE, 9(2), e89543. doi:10.1371/journal.pone.0089543

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

Enhanced polytomy resolution strengthens evidence for global gradient in speciation rate for marine fishes. https://fishtreeoflife.org/rabosky-et-al-2018-update/

Examples

## Not run: 
# Get cichlid rates and trees
rates <- fishtree_tip_rates(rank = "Cichlidae")
tree <- fishtree_phylogeny(rank = "Cichlidae")

# Plot tree and extract plotting data
plot(tree, show.tip.label = FALSE)
obj <- get("last_plot.phylo", ape::.PlotPhyloEnv)

# Generate a color ramp
ramp <- grDevices::colorRamp(c("black", "red"), bias = 10)
tiporder <- match(rates$species, gsub("_", " ", tree$tip.label))
scaled_rates <- rates$lambda.tv / max(rates$lambda.tv, na.rm = TRUE)
tipcols <- apply(ramp(scaled_rates), 1, function(x) do.call(rgb, as.list(x / 255)))

# Place colored bars
for (ii in 1:length(tiporder)) {
    tip <- tiporder[ii]
    lines(x = c(obj$xx[tip] + 0.5, obj$xx[tip] + 0.5 + scaled_rates[ii]),
          y = rep(obj$yy[tip], 2),
          col = tipcols[ii])
}

## End(Not run)