rtreeoflife

CRAN status R-CMD-check Lifecycle: experimental

rtreeoflife provides programmatic access to species records and selected FASTA files associated with the Royal Botanic Gardens, Kew Tree of Life Explorer. The package is designed for selective access: users search or match species first, then download only the FASTA files needed for an analysis.

The package includes tol_species, a normalized species/specimen index derived from the Tree of Life species list. This makes common searches available without mirroring the full Kew release locally.

Installation

Install the released version from CRAN with:

install.packages("rtreeoflife")

Install the development version from GitHub with:

pak::pak("PaulESantos/rtreeoflife")

Data Access Model

Kew release files are hosted at:

library(rtreeoflife)
tol_release_url()

The full release contains manifests, tree files, rendered tree assets, and many FASTA files. Downloading the complete repository can be slow and storage intensive, so the recommended workflow is:

  1. Search or match species in the bundled index.
  2. Resolve FASTA URLs for the selected records.
  3. Download to a temporary session directory.
  4. Manipulate the parsed FASTA data as tidy list-columns.
  5. Export FASTA files permanently only when needed.

Example

This example searches three species, downloads only the available FASTA files, summarises the recovered sequences, visualises the result with ggplot2, builds an exploratory tree for one shared gene, and exports FASTA files when the user decides to keep them.

library(dplyr)
library(ggplot2)

targets <- c(
  "Cnestis ferruginea",
  "Agelaea pentagyna",
  "Manotes expansa"
)

# Search the bundled species index.
matches <- tol_match_species(
  targets,
  multiple = "best"
)

matches |>
  select(
    requested_name,
    matched_name,
    match_type,
    has_data,
    sequence_id,
    no_of_genes_recovered,
    fasta_file_url
  )

# Keep only records with FASTA availability.
selected <- matches |>
  filter(has_data)

# Download selected FASTA files to a temporary directory.
# Increase timeout/retries for slow network connections.
download_plan <- tol_download_fasta(
  selected,
  timeout = 1200,
  retries = 5
)

# Parse FASTA files into a tidy list-column.
plan_nested <- download_plan |>
  tol_attach_fasta()

# Convert nested FASTA records to long tidy data.
fasta_long <- plan_nested |>
  tol_fasta_long()

fasta_long |>
  select(sequence_id, scientific_name, gene_id, width)

# Summarise and plot recovered FASTA content.
fasta_summary <- plan_nested |>
  tol_fasta_summary()

tol_plot_fasta_summary(fasta_summary)

# Identify shared genes and build an exploratory tree.
common_genes <- plan_nested |>
  tol_common_genes(min_records = 2)

tree_result <- plan_nested |>
  tol_build_gene_tree(
    gene_id = common_genes$gene_id[[1]],
    min_records = 2
  )

tol_plot_tree(tree_result)

# Export FASTA files permanently only if they should be retained.
exported <- download_plan |>
  tol_export_fasta(
    dest_dir = "raw-data/fasta/by_recovery",
    manifest_path = "raw-data/fasta/fasta_export_manifest.csv",
    overwrite = FALSE
  )

exported |>
  select(scientific_name, local_path, export_status)

Use exact taxonomic filters when the target group is known:

saxifraga <- tol_search_species(
  genus = "Saxifraga"
)

tol_plot_gene_recovery(saxifraga)

Use tol_match_species() when starting from a vector of scientific names:

tol_match_species(
  c("Cnestis ferruginea", "Agelaea pentagyna", "Manotes expansa"),
  multiple = "best"
)

Persistent Downloads

By default, tol_download_fasta() stores files in a temporary session directory. This keeps exploratory workflows lightweight:

plan <- tol_download_fasta(
  genus = "Saxifraga",
  specific_epithet = "fortunei"
)

plan |>
  tol_attach_fasta()

To keep files permanently, use tol_export_fasta():

plan |>
  tol_export_fasta(
    dest_dir = "raw-data/fasta/by_recovery"
  )

Release Utilities

Lower level helpers are available for metadata and small scoped downloads:

tol_known_bundles()

manifest_files <- tol_download_bundle("manifests")

species_tree <- tol_download_bundle("species_tree")

sequence_manifest <- tol_manifest(manifest_files[[1]])

For ordinary FASTA access, prefer the species-index workflow above instead of downloading complete release directories.

Citation

To cite the package and the original Kew Tree of Life Explorer data source, use:

citation("rtreeoflife")

When using Kew Tree of Life Explorer data, cite the original publication and indicate the data release used in the analysis.