Package {rtreeoflife}

Title: Access Tree of Life Data Releases
Version: 0.1.0
Description: Search species and specimen records from the Royal Botanic Gardens Tree of Life Explorer and retrieve selected genomic sequence files. Provides a bundled species index, tools for matching scientific names, and selective download helpers for sequence files. Supports tidy data workflows with list-columns, summaries, exploratory visualisation with 'ggplot2', and illustrative tree construction from shared genes.
License: MIT + file LICENSE
URL: https://github.com/PaulESantos/rtreeoflife, https://treeoflife.kew.org/, https://sftp.kew.org/pub/treeoflife/current_release/
BugReports: https://github.com/PaulESantos/rtreeoflife/issues
Depends: R (≥ 4.1.0)
Imports: cli, dplyr, ggplot2, tibble, tools, utils
Suggests: ape, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Encoding: UTF-8
LazyData: true
LazyDataCompression: xz
RoxygenNote: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-24 01:29:27 UTC; PC
Author: Paul E. Santos Andrade ORCID iD [aut, cre, cph]
Maintainer: Paul E. Santos Andrade <paulefrens@gmail.com>
Repository: CRAN
Date/Publication: 2026-08-04 09:40:02 UTC

Attach parsed FASTA data to a download plan

Description

Attach parsed FASTA data to a download plan

Usage

tol_attach_fasta(
  plan,
  column = "fasta",
  as = c("data.frame", "list", "text"),
  missing = c("empty", "error")
)

Arguments

plan

A data frame returned by tol_download_fasta(), tol_resolve_fasta(), or tol_save_fasta().

column

Name of the list-column to create.

as

FASTA representation passed to tol_read_fasta().

missing

What to store for missing files. "empty" stores an empty data frame/list/text value; "error" stops on the first missing file.

Value

A data frame with a FASTA list-column.

Kew Tree of Life base URL

Description

Kew Tree of Life base URL

Usage

tol_base_url()

Value

A character scalar with the default public Kew data URL.

Build an illustrative tree from one shared gene

Description

This helper is intended for exploration. It extracts one homologous gene from each selected FASTA, trims sequences to their common minimum length, computes raw DNA distances with ape, and returns an hclust tree plus the distance matrix. Rigorous phylogenetics should use explicit alignment and model selection outside this helper.

Usage

tol_build_gene_tree(plan, gene_id = NULL, min_records = 3)

Arguments

plan

A data frame returned by tol_attach_fasta() or a FASTA plan with local files.

gene_id

Optional gene id. If NULL, the most shared gene is selected.

min_records

Minimum records required to build the tree.

Value

A list with tree, distances, gene_id, sequences, and note.

Choose a gene shared by multiple downloaded FASTA files

Description

Choose a gene shared by multiple downloaded FASTA files

Usage

tol_common_genes(plan, min_records = 3)

Arguments

plan

A data frame returned by tol_attach_fasta() or a FASTA plan with local files.

min_records

Minimum number of records that must contain the gene.

Value

A tibble ranked by number of records and median width.

Local data directory for downloaded files

Description

The default can be overridden with option rtreeoflife.data_dir or environment variable RTREEOFLIFE_DATA_DIR.

Usage

tol_data_dir(create = TRUE)

Arguments

create

Create the directory if it does not exist.

Value

A normalized path.

Download files from a Kew Tree of Life release

Description

Download files from a Kew Tree of Life release

Usage

tol_download(
  paths,
  dest_dir = tol_data_dir(),
  release = "current_release",
  overwrite = FALSE,
  preserve_dirs = TRUE,
  quiet = FALSE,
  base_url = tol_base_url(),
  timeout = 600,
  retries = 3,
  retry_wait = 5
)

Arguments

paths

Character vector of file paths inside the release directory.

dest_dir

Local destination directory.

release

Release directory. Defaults to Kew's current release link.

overwrite

Replace existing local files.

preserve_dirs

Preserve the remote directory structure below dest_dir.

quiet

Passed to utils::download.file().

base_url

Base public URL.

timeout

Download timeout in seconds.

retries

Number of attempts for each file.

retry_wait

Seconds to wait between attempts.

Value

A character vector with local file paths.

Download a predefined Kew Tree of Life bundle

Description

Download a predefined Kew Tree of Life bundle

Usage

tol_download_bundle(
  bundle = "manifests",
  dest_dir = tol_data_dir(),
  release = "current_release",
  overwrite = FALSE,
  quiet = FALSE,
  base_url = tol_base_url(),
  timeout = 600,
  retries = 3,
  retry_wait = 5
)

Arguments

bundle

Bundle name. See tol_known_bundles().

dest_dir

Local destination directory.

release

Release directory. Defaults to Kew's current release link.

overwrite

Replace existing local files.

quiet

Passed to utils::download.file().

base_url

Base public URL.

timeout

Download timeout in seconds.

retries

Number of attempts for each file.

retry_wait

Seconds to wait between attempts.

Value

A character vector with local file paths.

Download and validate one directory from a Kew Tree of Life release

Description

Convenience wrapper around tol_download_release() for subdirectories such as "fasta/by_gene", "fasta/alignments", or "tree/species".

Usage

tol_download_directory(
  path,
  dest_dir = file.path("raw-data", normalize_release(release)),
  release = "current_release",
  manifest_path = file.path("raw-data", paste0("kew_download_", gsub("[^A-Za-z0-9]+",
    "_", normalize_remote_path(path)), ".csv")),
  overwrite = FALSE,
  validate_only = FALSE,
  quiet = FALSE,
  base_url = tol_base_url(),
  timeout = 600,
  retries = 5,
  retry_wait = 10
)

Arguments

path

Directory path inside the release.

dest_dir

Local destination directory for the release contents.

release

Release directory. Defaults to Kew's current release link.

manifest_path

Local CSV manifest path.

overwrite

Replace existing local files.

validate_only

Only index and validate existing local files.

quiet

Passed to utils::download.file().

base_url

Base public URL.

timeout

Download timeout in seconds.

retries

Number of attempts for each file.

retry_wait

Seconds to wait between attempts.

Value

A data frame with release id, remote paths, local paths, sizes, and validation status.

Download FASTA files for selected species records

Description

Download FASTA files for selected species records

Usage

tol_download_fasta(
  records = NULL,
  dest_dir = NULL,
  manifest_path = if (is.null(dest_dir)) NULL else file.path("raw-data",
    "kew_fasta_download_manifest.csv"),
  overwrite = FALSE,
  validate_only = FALSE,
  quiet = FALSE,
  timeout = 600,
  retries = 3,
  retry_wait = 5,
  ...
)

Arguments

records

Species records returned by tol_species_index() or tol_search_species(). If omitted, filters are applied to tol_species_index().

dest_dir

Local directory where FASTA files should be stored. If NULL, files are downloaded to a session temporary directory.

manifest_path

Optional CSV manifest path. Use NULL to skip writing. If dest_dir = NULL, no manifest is written unless this is explicitly set.

overwrite

Replace existing local FASTA files.

validate_only

Report local status without downloading.

quiet

Passed to utils::download.file().

timeout

Download timeout in seconds.

retries

Number of attempts for each file.

retry_wait

Seconds to wait between attempts.

...

Filters passed to tol_search_species() when records is omitted.

Value

A data frame with one row per requested FASTA.

Download and validate a complete Kew Tree of Life release

Description

This recursively indexes the remote release, downloads every file, validates local file sizes against the remote index, and writes a CSV manifest.

Usage

tol_download_release(
  dest_dir = file.path("raw-data", normalize_release(release)),
  path = "",
  release = "current_release",
  manifest_path = file.path("raw-data", "kew_download_manifest.csv"),
  overwrite = FALSE,
  validate_only = FALSE,
  quiet = FALSE,
  base_url = tol_base_url(),
  timeout = 600,
  retries = 3,
  retry_wait = 5
)

Arguments

dest_dir

Local destination directory for the release contents.

path

Directory path inside the release to download. Use "" for the whole release, or paths such as "fasta/by_gene".

release

Release directory. Defaults to Kew's current release link.

manifest_path

Local CSV manifest path.

overwrite

Replace existing local files.

validate_only

Only index and validate existing local files.

quiet

Passed to utils::download.file().

base_url

Base public URL.

timeout

Download timeout in seconds.

retries

Number of attempts for each file.

retry_wait

Seconds to wait between attempts.

Value

A data frame with release id, remote paths, local paths, sizes, and validation status.

Export downloaded FASTA files and a manifest

Description

Export downloaded FASTA files and a manifest

Usage

tol_export_fasta(
  plan,
  dest_dir = file.path("raw-data", "fasta", "by_recovery"),
  manifest_path = file.path(dest_dir, "fasta_export_manifest.csv"),
  overwrite = FALSE
)

Arguments

plan

A data frame returned by tol_download_fasta() or tol_resolve_fasta().

dest_dir

Permanent destination directory for FASTA files.

manifest_path

Optional CSV manifest path. If NULL, no manifest is written.

overwrite

Replace files that already exist in dest_dir.

Value

A tibble with copied file paths and export status.

Convert attached FASTA data to a tidy long table

Description

Convert attached FASTA data to a tidy long table

Usage

tol_fasta_long(plan, fasta_column = "fasta")

Arguments

plan

A data frame returned by tol_attach_fasta() or a FASTA plan with local files.

fasta_column

Name of the FASTA list-column. If it is not present, tol_attach_fasta() is called.

Value

A tibble with one row per sequence.

Summarise FASTA content by species record

Description

Summarise FASTA content by species record

Usage

tol_fasta_summary(plan)

Arguments

plan

A data frame returned by tol_attach_fasta() or a FASTA plan with local files.

Value

A tibble with one row per species/specimen FASTA.

List files and directories in a Kew Tree of Life remote index

Description

List files and directories in a Kew Tree of Life remote index

Usage

tol_index(path = "", release = "current_release", base_url = tol_base_url())

Arguments

path

Directory path inside the release.

release

Release directory. Defaults to Kew's current release link.

base_url

Base public URL.

Value

A data frame with name, path, url, and is_dir.

Known download bundles

Description

Alias for tol_known_bundles().

Usage

tol_known_bundle()

Value

A data frame with bundle names and included remote paths.

Known download bundles

Description

Known download bundles

Usage

tol_known_bundles()

Value

A data frame with bundle names and included remote paths.

Read a downloaded Kew Tree of Life manifest

Description

Read a downloaded Kew Tree of Life manifest

Usage

tol_manifest(file, manifest = NULL, ...)

Arguments

file

Local path to a manifest file.

manifest

Manifest type. Used only to assign column names when known.

...

Additional arguments passed to utils::read.delim().

Value

A data frame.

Match requested species names against the Kew Tree of Life index

Description

Match requested species names against the Kew Tree of Life index

Usage

tol_match_species(
  species,
  index = tol_species_index(),
  fuzzy = FALSE,
  max_distance = NULL,
  multiple = c("all", "best"),
  ignore_case = TRUE
)

Arguments

species

Character vector of requested scientific names.

index

A species index returned by tol_species_index(). If omitted, the built-in tol_species dataset is used.

fuzzy

If TRUE, return the closest available name when no exact match is found.

max_distance

Maximum edit distance for fuzzy matching. If NULL, a conservative threshold is computed from each requested name.

multiple

How to handle multiple records for the same matched species. "all" returns all records; "best" keeps the record with the highest no_of_genes_recovered and then no_of_bp_recovered.

ignore_case

Ignore case when matching names.

Value

A tibble with requested names, match status, matched records, and FASTA URLs where available.

Plot FASTA summary with ggplot2

Description

Plot FASTA summary with ggplot2

Usage

tol_plot_fasta_summary(summary)

Arguments

summary

A summary returned by tol_fasta_summary().

Value

A ggplot object.

Plot recovered gene counts with ggplot2

Description

Plot recovered gene counts with ggplot2

Usage

tol_plot_gene_recovery(records)

Arguments

records

Species records returned by tol_species_index() or tol_search_species().

Value

A ggplot object.

Plot an hclust tree with ggplot2

Description

Plot an hclust tree with ggplot2

Usage

tol_plot_tree(tree_result, label_offset = NULL, label_size = 3)

Arguments

tree_result

A result returned by tol_build_gene_tree() or an hclust object.

label_offset

Numeric offset used to place species labels beyond the end of each terminal branch. If NULL, an offset is computed from the tree height.

label_size

Label text size.

Value

A ggplot object.

Read a FASTA file

Description

Read a FASTA file

Usage

tol_read_fasta(file, as = c("data.frame", "list", "text"))

Arguments

file

Local FASTA file.

as

Output format. "data.frame" returns one row per sequence with header, sequence, and width; "list" returns a named character vector; "text" returns raw file lines.

Value

A data frame, named character vector, or character vector.

Build a URL for a Kew Tree of Life release

Description

Build a URL for a Kew Tree of Life release

Usage

tol_release_url(
  path = "",
  release = "current_release",
  base_url = tol_base_url()
)

Arguments

path

Optional path inside the release directory.

release

Release directory. Use "current_release" or "current" for Kew's current release link.

base_url

Base public URL.

Value

A character scalar URL.

Resolve FASTA download targets for selected species records

Description

Resolve FASTA download targets for selected species records

Usage

tol_resolve_fasta(records, dest_dir = NULL)

Arguments

records

Species records returned by tol_species_index() or tol_search_species().

dest_dir

Local directory where FASTA files should be stored. If NULL, a session temporary directory is used.

Value

A data frame describing FASTA URLs and local paths.

Save downloaded FASTA files to a permanent directory

Description

Save downloaded FASTA files to a permanent directory

Usage

tol_save_fasta(
  plan,
  dest_dir = file.path("raw-data", "fasta", "by_recovery"),
  overwrite = FALSE
)

Arguments

plan

A data frame returned by tol_download_fasta() or tol_resolve_fasta().

dest_dir

Permanent destination directory.

overwrite

Replace files that already exist in dest_dir.

Value

A copy of plan with updated local_path and status.

Search Kew Tree of Life species records

Description

Search Kew Tree of Life species records

Usage

tol_search_species(
  index = tol_species_index(),
  sequence_id = NULL,
  order = NULL,
  family = NULL,
  genus = NULL,
  specific_epithet = NULL,
  scientific_name = NULL,
  query = NULL,
  ignore_case = TRUE
)

Arguments

index

A species index returned by tol_species_index(). If omitted, the built-in tol_species dataset is used.

sequence_id

Optional sequence identifier or vector of identifiers.

order, family, genus, specific_epithet, scientific_name

Optional taxonomic filters.

query

Optional free-text query.

ignore_case

Ignore case in text filters.

Value

A filtered data frame.

Set the Kew Tree of Life base URL for the current R session

Description

Set the Kew Tree of Life base URL for the current R session

Usage

tol_set_base_url(base_url = "https://sftp.kew.org/pub/treeoflife")

Arguments

base_url

Base URL without the release directory.

Value

The previous value of option rtreeoflife.base_url, invisibly.

Kew Tree of Life species index

Description

A normalized species/specimen index exported from Kew Tree of Life Explorer. Each row represents one Tree of Life sequence record and includes taxonomic metadata, specimen metadata, recovery statistics, and the FASTA URL for the corresponding fasta/by_recovery file.

Usage

tol_species

Format

A tibble with 20485 rows and 16 columns:

sequence_id

Kew Tree of Life sequence identifier.

data_source

Project, dataset, or repository source.

order

Taxonomic order.

family

Taxonomic family.

genus

Taxonomic genus.

specific_epithet

Specific epithet or infraspecific name text.

specimen_reference

Voucher or specimen reference.

specimen_barcode

Specimen barcode where available.

collection_date

Collection year where available.

country_of_origin

Country of origin where available.

material_sampled

Sample material type.

no_of_genes_recovered

Number of recovered Angiosperms353 genes.

no_of_bp_recovered

Number of recovered base pairs.

fasta_file_url

Remote FASTA URL for this sequence recovery.

scientific_name

Combined genus and specific epithet.

fasta_file_name

Basename of fasta_file_url.

Source

Kew Tree of Life Explorer species list.

Read the Kew Tree of Life species index

Description

Read the Kew Tree of Life species index

Usage

tol_species_index(file = NULL, use_package_data = TRUE)

Arguments

file

Local path to all_species_list.csv. If NULL, the package dataset tol_species is returned.

use_package_data

Use the built-in tol_species dataset when file = NULL.

Value

A data frame with normalized column names and derived fields.