Package {phyloatlas}

Type: Package
Title: Access to the 'Phylo-Species Atlas' of Empirical Phylogenies
Version: 0.1.1
Description: Provides convenience functions to fetch standardized phylogenetic trees and per-tree provenance metadata from the 'Phylo-Species Atlas' https://github.com/franciscorichter/phylo-species-atlas directly from R. The atlas is a curated collection of empirical species-level trees covering Bacteria, Archaea, and Eukaryota, organized into 62 partitions of life with tip labels normalized against a shared dictionary of standardized species identifiers. Functions load any of the standardized trees with species labels resolved from the dictionary, list available trees, and inspect per-tree provenance.
License: MIT + file LICENSE
Encoding: UTF-8
URL: https://github.com/franciscorichter/phylo-species-atlas, https://franciscorichter.github.io/phylo-species-atlas/
BugReports: https://github.com/franciscorichter/phylo-species-atlas/issues
Depends: R (≥ 4.0)
Imports: ape, utils
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
VignetteBuilder: knitr
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-11-07 21:30:45 UTC; pancho
Author: Francisco Richter ORCID iD [aut, cre]
Maintainer: Francisco Richter <richtf@usi.ch>
Repository: CRAN
Date/Publication: 2026-11-07 22:20:14 UTC

phyloatlas: R access to the Phylo-Species Atlas

Description

Convenience functions to fetch phylogenetic trees and metadata from the Phylo-Species Atlas directly from R.

Details

Key functions: * [load_atlas_tree()] - load a tree by name, with species labels. * [list_trees()] - data frame of all available trees and metadata. * [atlas_info()] - metadata for a single tree. * [atlas_clear_cache()] - drop the in-session metadata/dictionary cache.

The atlas lives at <https://github.com/franciscorichter/phylo-species-atlas>.

Author(s)

Maintainer: Francisco Richter richtf@usi.ch (ORCID)

See Also

Useful links:

Clear the in-memory cache

Description

The dictionary and metadata files are downloaded once per R session and cached. Call this if you want to force a re-download (for example after switching 'phyloatlas.base_url').

Usage

atlas_clear_cache()

Value

Invisibly 'NULL'. Called for its side effect of emptying the internal cache environment.

See Also

Other atlas: atlas_info(), list_trees(), load_atlas_tree()

Examples

# Safe to run unconditionally — just empties the in-session cache.
atlas_clear_cache()

Get metadata for a single tree

Description

Get metadata for a single tree

Usage

atlas_info(name)

Arguments

name

Tree name without the '.nwk' extension (e.g. '"mammals"', '"birds"', '"fish"'). Must be a length-1 non-'NA' character string. Use [list_trees()] to see all available names.

Value

A one-row data frame with all metadata columns from [list_trees()], or 'NULL' (with a warning) if no tree by that name exists. Also returns 'NULL' (with a diagnostic message, no warning) if the atlas metadata cannot be downloaded.

See Also

Other atlas: atlas_clear_cache(), list_trees(), load_atlas_tree()

Examples


info <- atlas_info("mammals")
if (!is.null(info)) info

List trees available in the Phylo-Species Atlas

Description

Returns a data frame describing every standardized tree in the atlas: name, study, number of tips, whether the tree is time-calibrated, plus provenance fields (year, journal, DOI, coverage) when available.

Usage

list_trees()

Value

A data frame with one row per tree, ordered by group, with columns 'name', 'group', 'study', 'ntips', 'dated', 'year', 'journal', 'doi', 'crown_ma', 'described_species', 'coverage_pct', 'data_source', 'download_url', 'methods_brief', 'notes', and 'study_full' (the long-form study citation from the provenance file). Returns 'NULL' with a single diagnostic message if the atlas metadata cannot be downloaded (e.g. no internet); never throws on network failure.

See Also

Other atlas: atlas_clear_cache(), atlas_info(), load_atlas_tree()

Examples


trees <- list_trees()
if (!is.null(trees)) {
  head(trees)
  subset(trees, dated & ntips > 1000)
}

Load a tree from the Phylo-Species Atlas

Description

Downloads a standardized Newick tree from the atlas and resolves its integer tip IDs to species names using the shared dictionary.

Usage

load_atlas_tree(name, resolve_labels = TRUE)

Arguments

name

Tree name without the '.nwk' extension (e.g. '"mammals"', '"birds"', '"fish"', '"condamine_Vangidae"'). Use [list_trees()] to see all available names.

resolve_labels

If 'TRUE' (default) tip labels are replaced with standardized species names from 'dictionary.csv'. Set to 'FALSE' to keep the raw integer IDs (faster, avoids downloading the dictionary).

Some trees of the atlas are not redistributed, because their sources state no licence (the atlas's 'registers/withheld_trees.csv'). For such a name the function stops with an error that gives the address of the source, from which the tree can be downloaded; nothing is fetched.

Value

An object of class '"phylo"' from the ape package. If 'resolve_labels = TRUE' (the default), tip labels are species names from the standardized dictionary; otherwise tip labels are integer IDs as character strings.

See Also

Other atlas: atlas_clear_cache(), atlas_info(), list_trees()

Examples

# Offline demo using a small bundled tree (does not hit the network):
demo_path <- system.file("extdata", "tree_demo.nwk", package = "phyloatlas")
tree <- ape::read.tree(demo_path)
tree


# Live atlas fetch (requires internet):
tree <- try(load_atlas_tree("mammals"), silent = TRUE)
if (!inherits(tree, "try-error")) plot(tree, show.tip.label = FALSE)

# Keep integer IDs to skip the 18 MB dictionary download:
tree <- try(load_atlas_tree("birds", resolve_labels = FALSE), silent = TRUE)