| Title: | Interface to the Fish Tree of Life API |
|---|---|
| Description: | An interface to the Fish Tree of Life API to download taxonomies, phylogenies, fossil calibrations, and diversification rate information for ray-finned fishes. |
| Authors: | Jonathan Chang [aut, cre] (ORCID: <https://orcid.org/0000-0002-3811-1254>), Michael E Alfaro [ctb], Daniel L Rabosky [ctb], Stephen A Smith [ctb] |
| Maintainer: | Jonathan Chang <[email protected]> |
| License: | BSD_2_clause + file LICENSE |
| Version: | 0.4.0.9000 |
| Built: | 2026-11-03 04:23:23 UTC |
| Source: | https://github.com/jonchang/fishtree |
Retrieves an aligned sequence via the Fish Tree of Life API. If neither 'species' nor 'taxon' are specified, returns the entire sequence matrix.
fishtree_alignment( species, taxon, split = FALSE, release = getOption("fishtree.release", .default_release), rank = deprecated() )fishtree_alignment( species, taxon, split = FALSE, release = getOption("fishtree.release", .default_release), rank = deprecated() )
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"'). |
split |
Splits the output into a list by gene locus. |
release |
The tree release to use, from |
rank |
Deprecated; use 'taxon' instead. |
An object of class '"DNAbin"', or a named list of the same if 'split = TRUE“
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
## Not run: surgeon_dna <- fishtree_alignment(taxon = "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)## Not run: surgeon_dna <- fishtree_alignment(taxon = "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)
Files from a release are downloaded once, checked against the release's checksums, and kept in a cache. 'fishtree_cache_info()' lists the cached files and 'fishtree_cache_clear()' deletes them. Cached files that the data manifest no longer lists are deleted whenever fishtree downloads a file.
fishtree_cache_info() fishtree_cache_clear()fishtree_cache_info() fishtree_cache_clear()
The cache is in 'tools::R_user_dir("fishtree", "cache")'. Set 'options(fishtree.cache_dir = ...)' to use another directory.
'fishtree_cache_info()' returns a data frame with the 'file' name (its SHA-256), 'bytes' and 'modified' time of each cached file. 'fishtree_cache_clear()' returns the number of files deleted, invisibly.
## Not run: fishtree_cache_info() fishtree_cache_clear() ## End(Not run)## Not run: fishtree_cache_info() fishtree_cache_clear() ## End(Not run)
Retrieves a complete phylogeny generated by stochastic polytomy resolution via the Fish Tree of Life API. If neither 'species' nor 'taxon' 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.
fishtree_complete_phylogeny( species, taxon, mc.cores = getOption("mc.cores", 1L), release = getOption("fishtree.release", .default_release), rank = deprecated() )fishtree_complete_phylogeny( species, taxon, mc.cores = getOption("mc.cores", 1L), release = getOption("fishtree.release", .default_release), rank = deprecated() )
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"'). |
mc.cores |
Number of cores to use in mclapply when subsetting the tree (default '1') |
release |
The tree release to use, from |
rank |
Deprecated; use 'taxon' instead. |
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.
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/
## Not run: tree <- fishtree_complete_phylogeny(taxon = "Acanthuridae") sampled_tips <- fishtree_phylogeny(taxon = "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)## Not run: tree <- fishtree_complete_phylogeny(taxon = "Acanthuridae") sampled_tips <- fishtree_phylogeny(taxon = "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)
Retrieves a phylogeny via the Fish Tree of Life API. If neither 'species' nor 'taxon' are specified, returns the entire phylogeny.
fishtree_phylogeny( species, taxon, type = c("chronogram", "phylogram", "chronogram_mrca", "phylogram_mrca"), release = getOption("fishtree.release", .default_release), rank = deprecated() )fishtree_phylogeny( species, taxon, type = c("chronogram", "phylogram", "chronogram_mrca", "phylogram_mrca"), release = getOption("fishtree.release", .default_release), rank = deprecated() )
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 |
rank |
Deprecated; use 'taxon' instead. |
For maximum interoperability, 'species' considers spaces and underscores equivalently. Internally, the phylogenies use underscores.
An object of class '"phylo"'.
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
fishtree_rogues, read.tree, force.ultrametric
## Not run: # 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) ## End(Not run)## Not run: # 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) ## End(Not run)
Describes one tree release. Includes citation information and checksums.
fishtree_release(release = getOption("fishtree.release", .default_release))fishtree_release(release = getOption("fishtree.release", .default_release))
release |
The release's id, from |
A list with the release's 'id', 'title', 'status', 'citation', 'doi', 'license' and 'native_taxonomy', and 'files', a data frame of its files.
fishtree_releases to list releases.
## Not run: rel <- fishtree_release("R2018") rel$citation rel$files[, c("role", "url", "bytes")] ## End(Not run)## Not run: rel <- fishtree_release("R2018") rel$citation rel$files[, c("role", "url", "bytes")] ## End(Not run)
Lists every release available on the Fish Tree of Life. Choose one with the 'release' argument of the other functions, or for the whole session with 'options(fishtree.release = "...")'.
fishtree_releases()fishtree_releases()
A data frame with one row per release, with columns 'id', 'title', 'status', 'native_taxonomy', 'doi' and 'citation'.
fishtree_release for one release's citation and files.
## Not run: fishtree_releases() ## End(Not run)## Not run: fishtree_releases() ## End(Not run)
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.
fishtree_rogues( taxon, release = getOption("fishtree.release", .default_release), rank = deprecated() )fishtree_rogues( taxon, release = getOption("fishtree.release", .default_release), rank = deprecated() )
taxon |
the (possibly paraphyletic) taxon for which rogue or intruder species should be identified. |
release |
The tree release to use, from |
rank |
Deprecated; use 'taxon' instead. |
A vector of species names, potentially empty.
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
## Not run: fishtree_rogues("Gobiidae") # several rogue taxa! fishtree_rogues("Labridae") # nice and monophlyetic ## End(Not run)## Not run: fishtree_rogues("Gobiidae") # several rogue taxa! fishtree_rogues("Labridae") # nice and monophlyetic ## End(Not run)
Retrieves taxonomic and other information from the Fish Tree of Life API.
fishtree_taxonomy( taxon = NULL, release = getOption("fishtree.release", .default_release), ranks = deprecated() )fishtree_taxonomy( taxon = NULL, release = getOption("fishtree.release", .default_release), ranks = deprecated() )
taxon |
One or more taxon names to retrieve, such as '"Labridae"'. |
release |
The tree release to use, from |
ranks |
Deprecated; use 'taxon' instead. |
If 'taxon' is unspecified, a data frame of all valid taxa, with columns 'rank' and 'name'. Otherwise, a list with one element per taxon, named by taxon. Each element is a list with:
All species in the taxon.
The species in the taxon that are in the phylogeny.
The species in the taxon that are not in the phylogeny.
A list, named by rank, of the names at each rank among the taxon's species. Look up ranks by name, as in 'taxonomy$order'; which ranks are present, and their order, depend on the taxonomy.
Future versions of fishtree will keep these fields and the columns of the
data frame. The other fields are deprecated and will be removed in
fishtree 1.0: use fishtree_rogues instead of 'rogues';
fishtree_tip_rates instead of 'tiprates_dr',
'tiprates_bamm_lambda', 'tiprates_bamm_mu', 'mean_dr', 'mean_bamm_lambda'
and 'mean_bamm_mu'; and fishtree_phylogeny and
fishtree_alignment instead of the download paths
'chronogram', 'phylogram', 'chronogram_mrca', 'phylogram_mrca',
'matrix_phylip' and 'matrix_nexus'. 'gene_sampling' has no replacement.
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
## Not run: tax <- fishtree_taxonomy("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)## Not run: tax <- fishtree_taxonomy("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)
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 'taxon' are specified, returns the entire set of tip-specific diversification rates.
fishtree_tip_rates( species, taxon, sampled_only = TRUE, release = getOption("fishtree.release", .default_release), rank = deprecated() )fishtree_tip_rates( species, taxon, sampled_only = TRUE, release = getOption("fishtree.release", .default_release), rank = deprecated() )
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"'). |
sampled_only |
Restricts the returned dataset to only those species that have genetic data available. Defaults to 'TRUE'. |
release |
The tree release to use, from |
rank |
Deprecated; use 'taxon' instead. |
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.
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/
## Not run: # Get cichlid rates and trees rates <- fishtree_tip_rates(taxon = "Cichlidae") tree <- fishtree_phylogeny(taxon = "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)## Not run: # Get cichlid rates and trees rates <- fishtree_tip_rates(taxon = "Cichlidae") tree <- fishtree_phylogeny(taxon = "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)