Package {fishtree}

Type:	Package
Title:	Interface to the Fish Tree of Life API
Version:	0.4.0
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
RoxygenNote:	7.3.3
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), lifecycle (≥ 1.0.0), memoise, parallel, rlang (≥ 0.4.1), utils
Suggests:	diversitree, geiger, hisse (≥ 2.1.11), knitr, markdown, phytools, picante, rfishbase (≥ 4.1.2), rmarkdown, spelling, testthat (≥ 3.1.7), withr
VignetteBuilder:	knitr
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-11-02 23:43:23 UTC; jonchang
Author:	Jonathan Chang [aut, cre], Michael E Alfaro [ctb], Daniel L Rabosky [ctb], Stephen A Smith [ctb]
Maintainer:	Jonathan Chang <me@jonathanchang.org>
Repository:	CRAN
Date/Publication:	2026-11-03 00:30:02 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. It keeps downloaded files in a cache on disk (see fishtree_cache_info) and their (sometimes large) parsed results in memory, so long-running R instances could use a lot of memory.

Author(s)

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

Other contributors:

• Michael E Alfaro [contributor]

• Daniel L Rabosky [contributor]

• Stephen A Smith [contributor]

See Also

Useful links:

• https://fishtreeoflife.org/

• https://github.com/jonchang/fishtree

• Report bugs at https://github.com/jonchang/fishtree/issues

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 'taxon' are specified, returns the entire sequence matrix.

Usage

fishtree_alignment(
  species,
  taxon,
  split = FALSE,
  release = getOption("fishtree.release", .default_release),
  rank = deprecated()
)

Arguments

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(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)

Manage the Fish Tree of Life download cache

Description

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.

Usage

fishtree_cache_info()

fishtree_cache_clear()

Details

The cache is in 'tools::R_user_dir("fishtree", "cache")'. Set 'options(fishtree.cache_dir = ...)' to use another directory.

Value

'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.

Examples

## Not run: 
fishtree_cache_info()
fishtree_cache_clear()

## 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 '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.

Usage

fishtree_complete_phylogeny(
  species,
  taxon,
  mc.cores = getOption("mc.cores", 1L),
  release = getOption("fishtree.release", .default_release),
  rank = deprecated()
)

Arguments

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(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)

Get a phylogeny from the Fish Tree of Life

Description

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

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 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)

Get the details of a Fish Tree of Life release

Description

Describes one tree release. Includes citation information and checksums.

Usage

fishtree_release(release = getOption("fishtree.release", .default_release))

Arguments

Value

A list with the release's 'id', 'title', 'status', 'citation', 'doi', 'license' and 'native_taxonomy', and 'files', a data frame of its files.

See Also

fishtree_releases to list releases.

Examples

## Not run: 
rel <- fishtree_release("R2018")
rel$citation
rel$files[, c("role", "url", "bytes")]

## End(Not run)

List releases on the Fish Tree of Life

Description

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 = "...")'.

Usage

fishtree_releases()

Value

A data frame with one row per release, with columns 'id', 'title', 'status', 'native_taxonomy', 'doi' and 'citation'.

See Also

fishtree_release for one release's citation and files.

Examples

## Not run: 
fishtree_releases()

## 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(
  taxon,
  release = getOption("fishtree.release", .default_release),
  rank = deprecated()
)

Arguments

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(
  taxon = NULL,
  release = getOption("fishtree.release", .default_release),
  ranks = deprecated()
)

Arguments

Value

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:

'species'

All species in the taxon.

'sampled_species'

The species in the taxon that are in the phylogeny.

'unsampled_species'

The species in the taxon that are not in the phylogeny.

'taxonomy'

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.

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("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 'taxon' are specified, returns the entire set of tip-specific diversification rates.

Usage

fishtree_tip_rates(
  species,
  taxon,
  sampled_only = TRUE,
  release = getOption("fishtree.release", .default_release),
  rank = deprecated()
)

Arguments

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(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)