Package 'taxodist'

taxodist: Taxonomic Distance and Phylogenetic Lineage Computation

Description

taxodist computes phylogenetic distances between any two taxa using hierarchical lineage data retrieved from The Taxonomicon (taxonomy.nl), a comprehensive curated classification of all life based on Systema Naturae 2000.

Core functions

• get_lineage() — retrieve the full lineage of any taxon

• taxo_distance() — compute the tree metric distance between two taxa

• mrca() — find the most recent common ancestor

• distance_matrix() — compute all pairwise distances for a set of taxa

• closest_relative() — find the closest relative among candidates

• compare_lineages() — print a side-by-side lineage comparison

• shared_clades() — list clades shared between two taxa

• is_member() — test clade membership

• filter_clade() — filter taxa by clade membership

• check_coverage() — check Taxonomicon coverage for a list of taxa

• lineage_depth() — get the lineage depth of a taxon

• clear_cache() — clear the session lineage cache

Mathematical background

The distance metric is based on the depth of the most recent common ancestor (MRCA):

$d(A, B) = \frac{1}{\text{depth}(\text{MRCA}(A,B))}$

The deeper the shared ancestor, the smaller the distance. This metric ensures that taxa sharing the same MRCA are always equidistant from any third taxon, regardless of lineage depth below the split — a key biological correctness property absent from Jaccard-based approaches.

Data source

All lineage data is sourced from The Taxonomicon (taxonomy.nl), based on Systema Naturae 2000 by S.J. Brands (1989 onwards). Please cite this resource when using taxodist in published work.

Author(s)

Maintainer: Rodrigo Fonseca Villa [email protected] (ORCID)

References

Brands, S.J. (1989 onwards). Systema Naturae 2000. Amsterdam, The Netherlands. Retrieved from The Taxonomicon, http://taxonomicon.taxonomy.nl.

See Also

Useful links:

• https://github.com/rodrigosqrt3/taxodist

• Report bugs at https://github.com/rodrigosqrt3/taxodist/issues

---

Inspect the current taxodist lineage cache

Description

Reports the number of cached entries, their total memory footprint, and the names of all taxa whose lineages are stored in the current session. Useful for understanding what has already been retrieved before running further computations.

Usage

cache_info()

Value

Invisibly returns a list with elements:

n_lineages

Integer. Number of cached lineages.

n_ids

Integer. Number of cached taxon IDs.

taxa

Character vector of taxa with cached lineages.

size_bytes

Numeric. Total memory used by the cache.

See Also

save_cache(), load_cache(), clear_cache()

Examples

get_lineage("Tyrannosaurus")
get_lineage("Velociraptor")
cache_info()

---

Check whether a taxon is covered by The Taxonomicon

Description

Queries The Taxonomicon for a taxon name and returns a logical indicating whether the taxon was found. Useful for pre-screening a list of names before running distance computations.

Usage

check_coverage(taxa, verbose = FALSE)

Arguments

taxa	A character vector of one or more taxon names.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A named logical vector. TRUE indicates the taxon was found, FALSE indicates it was not.

Examples

check_coverage(c("Tyrannosaurus", "Velociraptor", "Fakeosaurus"))

---

Clear the taxodist lineage cache

Description

Clears all cached lineages stored in the current R session. Useful when you suspect cached data is stale or want to force fresh retrieval.

Usage

clear_cache()

Value

Invisibly returns NULL.

Examples

clear_cache()

---

Find the closest relative of a taxon among a set of candidates

Description

Given a query taxon and a vector of candidate taxa, returns the candidate with the smallest phylogenetic distance to the query.

Usage

closest_relative(taxon, candidates, verbose = FALSE)

Arguments

taxon	A character string giving the query taxon name.
candidates	A character vector of candidate taxon names to compare against.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A data frame with columns taxon (candidate name) and distance (tree metric distance), sorted by distance ascending. Returns NULL if the query taxon cannot be found.

Examples

closest_relative("Tyrannosaurus",
  c("Velociraptor", "Triceratops", "Brachiosaurus", "Allosaurus"))

---

Compare lineages of two taxa side by side

Description

Prints the lineages of two taxa aligned at their most recent common ancestor, making the point of divergence easy to identify.

Usage

compare_lineages(taxon_a, taxon_b, verbose = FALSE)

Arguments

taxon_a	A character string giving the first taxon name.
taxon_b	A character string giving the second taxon name.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

Invisibly returns a list with elements lineage_a, lineage_b, and mrca_depth.

Examples

compare_lineages("Tyrannosaurus", "Velociraptor")
compare_lineages("Tyrannosaurus", "Triceratops")

---

Compute pairwise taxonomic distances for a set of taxa

Description

Given a vector of taxon names, computes all pairwise phylogenetic distances and returns a symmetric distance matrix. Lineages are cached after first retrieval to minimise redundant network requests.

Usage

distance_matrix(taxa, verbose = FALSE, progress = TRUE)

Arguments

taxa	A character vector of taxon names.
verbose	Logical. If TRUE, prints progress for each pair. Default FALSE.
progress	Logical. If TRUE, shows a progress bar. Default TRUE.

Value

A symmetric numeric matrix of class "dist" containing pairwise distances. Row and column names are set to the input taxon names. Taxa that could not be found are included with NA distances.

See Also

taxo_distance(), closest_relative()

Examples

theropods <- c("Tyrannosaurus", "Velociraptor", "Spinosaurus",
               "Allosaurus", "Carnotaurus")
mat <- distance_matrix(theropods)
print(mat)

---

Filter a vector of taxa to those belonging to a given clade

Description

Given a vector of taxon names and a clade name, returns only those taxa whose lineage includes the specified clade.

Usage

filter_clade(taxa, clade, verbose = FALSE)

Arguments

taxa	A character vector of taxon names.
clade	A character string giving the clade to filter by.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A character vector of taxa that are members of the specified clade.

Examples

taxa <- c("Tyrannosaurus", "Triceratops", "Velociraptor",
          "Brachiosaurus", "Homo")
filter_clade(taxa, "Theropoda")
filter_clade(taxa, "Dinosauria")

---

Compute distances from a focal taxon to a community of taxa

Description

Given a focal taxon and a vector of community taxa, retrieves all lineages and computes the taxonomic distance from the focal taxon to each member of the community. Returns a sorted data frame that also reports the most recent common ancestor (MRCA) for each pair, making it easy to interpret why a taxon is close or distant.

Usage

focal_distances(focal, community, verbose = FALSE, progress = TRUE)

Arguments

focal	A character string giving the focal taxon name.
community	A character vector of community taxon names to compare against. The focal taxon may be included — it will receive a distance of 0.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.
progress	Logical. If TRUE, shows a progress bar. Default TRUE.

Value

A data frame of class "taxodist_focal" with columns:

taxon

Character. Community taxon name.

distance

Numeric. Taxonomic distance to the focal taxon.

mrca

Character. Name of the most recent common ancestor.

mrca_depth

Integer. Depth of the MRCA node.

Rows are sorted by distance ascending (closest relatives first). Returns NULL if the focal taxon cannot be found.

See Also

closest_relative(), distance_matrix(), taxo_distance()

Examples

community <- c("Velociraptor", "Triceratops", "Brachiosaurus",
               "Allosaurus", "Homo", "Quercus")
focal_distances("Tyrannosaurus", community)

---

Retrieve the full taxonomic lineage of a taxon by name

Description

A convenience wrapper that combines get_taxonomicon_id() and get_lineage_by_id() into a single call. Given a taxon name, returns its complete lineage from root to tip.

Usage

get_lineage(taxon, clean = TRUE, verbose = FALSE)

Arguments

taxon	A character string giving the taxon name.
clean	Logical. If TRUE (default), removes philosophical root nodes and cleans formatting markers.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A character vector of clade names ordered from root to tip, or NULL if the taxon cannot be found.

Examples

get_lineage("Tyrannosaurus")
get_lineage("Homo sapiens")
get_lineage("Quercus robur")

---

Retrieve the full taxonomic lineage of a taxon

Description

Given a Taxonomicon numeric ID, retrieves and parses the complete hierarchical lineage from root (Natura) to the taxon itself. The lineage is returned as a character vector ordered from root to tip.

Usage

get_lineage_by_id(taxon_id, clean = TRUE, verbose = FALSE)

Arguments

taxon_id	A numeric or character string giving the Taxonomicon ID. Obtain this with get_taxonomicon_id().
clean	Logical. If TRUE (default), removes philosophical root nodes above Biota (i.e., Natura, actualia, Mundus, naturalia) and strips dagger and superscript markers from names.
verbose	Logical. If TRUE, prints status messages. Default FALSE.

Details

Lineage data is sourced from The Taxonomicon, which is based on Systema Naturae 2000 (Brands, S.J., 1989 onwards). The depth of lineages in The Taxonomicon substantially exceeds that of other programmatic sources such as the Open Tree of Life, particularly for well-studied clades such as Dinosauria, where intermediate clades at the level of superfamilies, tribes, and named subclades are fully resolved.

Value

A character vector of clade names from root to tip, or NULL if retrieval fails.

See Also

get_lineage(), taxo_distance()

Examples

id <- get_taxonomicon_id("Tyrannosaurus")
lin <- get_lineage_by_id(id)
print(lin)

---

Find the Taxonomicon ID for a taxon name

Description

Queries The Taxonomicon (taxonomy.nl) to retrieve the internal numeric identifier for a given taxon name. The search filters out non-biological entities such as astronomical objects that may share the same name.

Usage

get_taxonomicon_id(taxon, verbose = FALSE)

Arguments

taxon	A character string giving the taxon name to search for. Typically a genus name (e.g., "Tyrannosaurus") but species and higher ranks are also supported.
verbose	Logical. If TRUE, prints status messages during retrieval. Default is FALSE.

Details

The function queries the static search endpoint at taxonomicon.taxonomy.nl/TaxonList.aspx and parses the resulting HTML to extract the taxon ID from the hierarchy link. When multiple matches exist (e.g., a genus name shared with an astronomical object), biological entries are prioritised by filtering for entries annotated as dinosaur, reptile, archosaur, animal, plant, fungus, or bacterium.

Value

A character string containing the Taxonomicon numeric ID, or NULL if the taxon is not found.

See Also

get_lineage(), taxo_distance()

Examples

get_taxonomicon_id("Tyrannosaurus")   # returns "50841"
get_taxonomicon_id("Homo")
get_taxonomicon_id("Quercus")

---

Test whether one taxon is nested within another

Description

Returns TRUE if taxon is a member of clade — i.e., if the clade name appears in the taxon's lineage.

Usage

is_member(taxon, clade, verbose = FALSE)

Arguments

taxon	A character string giving the taxon name to test.
clade	A character string giving the clade name to test membership in.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A logical value, or NULL if the taxon cannot be found.

Examples

is_member("Tyrannosaurus", "Theropoda")    # TRUE
is_member("Triceratops", "Theropoda")      # FALSE
is_member("Homo", "Amniota")               # TRUE

---

Get the lineage depth of a taxon

Description

Returns the number of nodes in the lineage of a taxon, from root to tip. This reflects how deeply nested the taxon is within the taxonomic hierarchy.

Usage

lineage_depth(taxon, verbose = FALSE)

Arguments

taxon	A character string giving the taxon name.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

An integer giving the lineage depth, or NULL if the taxon cannot be found.

Examples

lineage_depth("Tyrannosaurus")   # deep — many intermediate clades
lineage_depth("Biota")           # shallow — near root

---

Load a previously saved taxodist cache from disk

Description

Restores lineage data saved with save_cache() into the current session cache, avoiding network requests for taxa already retrieved in a previous session.

Usage

load_cache(file)

Arguments

file	Path to an .rds file created by save_cache().

Value

Invisibly returns NULL.

See Also

save_cache(), clear_cache()

Examples

tmp <- tempfile(fileext = ".rds")
save_cache(tmp)
load_cache(tmp)
unlink(tmp)

---

Compute the most recent common ancestor of two taxa

Description

Retrieves the lineages of two taxa and returns the name of their most recent common ancestor (MRCA) — the deepest node shared by both lineages.

Usage

mrca(taxon_a, taxon_b, verbose = FALSE)

Arguments

taxon_a	A character string giving the first taxon name.
taxon_b	A character string giving the second taxon name.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A character string giving the name of the MRCA, or NULL if either taxon cannot be found or no common ancestor exists.

Examples

mrca("Tyrannosaurus", "Velociraptor")   # "Tyrannoraptora"
mrca("Tyrannosaurus", "Triceratops")    # "Dinosauria"
mrca("Tyrannosaurus", "Homo")           # "Amniota"

---

Plot method for taxodist_cluster objects

Description

Plots the hierarchical clustering dendrogram produced by taxo_cluster().

Usage

## S3 method for class 'taxodist_cluster'
plot(
  x,
  main = "Taxonomic Clustering",
  xlab = "",
  sub = paste("Method:", if (!is.null(x$hclust)) x$hclust$method else "None"),
  ...
)

Arguments

x	A taxodist_cluster object from taxo_cluster().
main	Plot title. Default: "Taxonomic Clustering".
xlab	X-axis label. Default: "".
sub	Subtitle. Default: clustering method used.
...	Additional arguments passed to stats::plot.hclust().

Value

Invisibly returns x. Called for side effects (plotting).

Examples

taxa <- c("Tyrannosaurus", "Velociraptor", "Triceratops", "Brachiosaurus")
cl <- taxo_cluster(taxa)
plot(cl)

---

Plot method for taxodist_ord objects

Description

Plots the PCoA ordination produced by taxo_ordinate().

Usage

## S3 method for class 'taxodist_ord'
plot(
  x,
  main = "Taxonomic Ordination (PCoA)",
  xlab = "PC1",
  ylab = "PC2",
  labels = if (!is.null(x$points)) rownames(x$points) else NULL,
  ...
)

Arguments

x	A taxodist_ord object from taxo_ordinate().
main	Plot title. Default: "Taxonomic Ordination (PCoA)".
xlab	X-axis label. Default: "PC1".
ylab	Y-axis label. Default: "PC2".
labels	Character vector of labels. Default: rownames of points.
...	Additional arguments passed to graphics::text().

Value

Invisibly returns x. Called for side effects (plotting).

Examples

taxa <- c("Tyrannosaurus", "Velociraptor", "Triceratops", "Brachiosaurus")
ord <- taxo_ordinate(taxa)
plot(ord)

---

Print method for taxodist_focal objects

Description

Print method for taxodist_focal objects

Usage

## S3 method for class 'taxodist_focal'
print(x, ...)

Arguments

x	A taxodist_focal object from focal_distances().
...	Additional arguments (ignored).

Value

Invisibly returns x. Called for side effects (printing).

---

Print method for taxodist_path objects

Description

Print method for taxodist_path objects

Usage

## S3 method for class 'taxodist_path'
print(x, ...)

Arguments

x	A taxodist_path object from taxo_path().
...	Additional arguments (ignored).

Value

Invisibly returns x. Called for side effects (printing).

---

Print method for taxodist distance results

Description

Print method for taxodist distance results

Usage

## S3 method for class 'taxodist_result'
print(x, ...)

Arguments

x	A list returned by taxo_distance().
...	Additional arguments (ignored).

Value

Invisibly returns x. Called for side effects (printing).

---

Save the taxodist lineage cache to disk

Description

Serialises the current session cache to an .rds file so it can be restored in a future session with load_cache(). Useful for reproducibility and for avoiding repeated network requests.

Usage

save_cache(file)

Arguments

file	Path to the .rds file to write.

Value

Invisibly returns NULL.

See Also

load_cache(), clear_cache()

Examples

tmp <- tempfile(fileext = ".rds")
save_cache(tmp)
unlink(tmp)

---

List all clades shared between two taxa

Description

Returns the vector of clade names forming the shared trunk of two taxa's lineages, from root down to (and including) their MRCA.

Usage

shared_clades(taxon_a, taxon_b, verbose = FALSE)

Arguments

taxon_a	A character string giving the first taxon name.
taxon_b	A character string giving the second taxon name.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A character vector of shared clade names ordered from root to MRCA, or NULL if either taxon cannot be found.

Examples

shared_clades("Tyrannosaurus", "Velociraptor")
shared_clades("Tyrannosaurus", "Homo")

---

Summary method for taxodist_ord objects

Description

Prints a summary of the PCoA ordination, including the goodness-of-fit and the proportion of variance explained by each principal coordinate.

Usage

## S3 method for class 'taxodist_ord'
summary(object, ...)

Arguments

object	A taxodist_ord object from taxo_ordinate.
...	Additional arguments (ignored).

Value

Invisibly returns a data frame containing the eigenvalues and variance explained by each dimension.

---

Cluster taxa by taxonomic distance

Description

Computes pairwise taxonomic distances and performs hierarchical clustering.

Usage

taxo_cluster(taxa, method = "average", ...)

Arguments

taxa	A character vector of taxon names, or a dist object from distance_matrix().
method	Clustering method passed to stats::hclust(). Default "average" (UPGMA), which works well with taxonomic distances.
...	Additional arguments passed to distance_matrix() (e.g. verbose, progress).

Value

An object of class "taxodist_cluster" — a list with:

hclust

The stats::hclust() result.

dist

The underlying distance matrix.

See Also

taxo_ordinate(), distance_matrix()

Examples

taxa <- c("Tyrannosaurus", "Velociraptor", "Triceratops", "Brachiosaurus")
cl <- taxo_cluster(taxa)
if (!is.null(cl$hclust)) {
  plot(cl)
}

---

Compute the phylogenetic distance between two taxa

Description

Given two taxon names, retrieves their lineages from The Taxonomicon and computes a taxonomic distance based on the depth of their most recent common ancestor (MRCA):

Usage

taxo_distance(taxon_a, taxon_b, verbose = FALSE)

Arguments

taxon_a	A character string giving the first taxon name.
taxon_b	A character string giving the second taxon name.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Details

$d(A, B) = \frac{1}{\text{depth}(\text{MRCA}(A,B))}$

The deeper the shared ancestor, the smaller (closer to zero) the distance. This metric ensures that taxa diverging at the same node are always equidistant from any third taxon, regardless of lineage depth differences below the split.

Value

A named list of class "taxodist_result" with the following elements:

distance

Numeric. The distance between the two taxa. Returns 0 if one taxon is an ancestor of the other.

mrca

Character. The name of the most recent common ancestor.

mrca_depth

Integer. The depth of the MRCA node.

depth_a

Integer. The lineage depth of taxon A.

depth_b

Integer. The lineage depth of taxon B.

taxon_a

Character. Name of the first taxon.

taxon_b

Character. Name of the second taxon.

Returns NULL if either taxon cannot be found.

References

Brands, S.J. (1989 onwards). Systema Naturae 2000. Amsterdam, The Netherlands. Retrieved from The Taxonomicon, http://taxonomicon.taxonomy.nl.

See Also

mrca(), distance_matrix(), get_lineage()

Examples

# Distance between two theropods
taxo_distance("Tyrannosaurus", "Velociraptor")

# Distance between very distantly related taxa
taxo_distance("Tyrannosaurus", "Quercus")

# Distance between two oviraptorid genera
taxo_distance("Nomingia", "Huanansaurus")

---

Plot a taxonomic heatmap

Description

Computes pairwise taxonomic distances and plots a heatmap with hierarchical clustering dendrograms on the margins. Darker/hotter colors typically represent smaller distances (closer relatives).

Usage

taxo_heatmap(taxa, ...)

Arguments

taxa	A character vector of taxon names, or a dist object from distance_matrix.
...	Additional arguments passed to heatmap.

Value

Invisibly returns the underlying dist object. Called primarily for its side effect (plotting).

Examples

taxa <- c("Tyrannosaurus", "Velociraptor", "Homo", "Panthera", "Quercus")
taxo_heatmap(taxa)

---

Ordinate taxa in taxonomic distance space

Description

Computes pairwise taxonomic distances and applies classical multidimensional scaling (PCoA) to project taxa into a low-dimensional space.

Usage

taxo_ordinate(taxa, k = 2, ...)

Arguments

taxa	A character vector of taxon names, or a dist object from distance_matrix().
k	Number of dimensions. Default 2.
...	Additional arguments passed to distance_matrix().

Value

An object of class "taxodist_ord" — a list with:

points

A matrix of coordinates (taxa x k dimensions).

dist

The underlying distance matrix.

GOF

Goodness-of-fit fromstats::cmdscale().

eig

The eigenvalues computed during PCoA.

See Also

taxo_cluster(), distance_matrix()

Examples

taxa <- c("Tyrannosaurus", "Velociraptor", "Triceratops", "Brachiosaurus")
ord <- taxo_ordinate(taxa)
if (!is.null(ord$points)) {
  plot(ord$points, type = "n")
  text(ord$points, labels = rownames(ord$points))
}

---

Get the taxonomic path between two taxa

Description

Returns the full node-by-node path from one taxon up to their most recent common ancestor (MRCA) and back down to the other taxon. The result is a data frame with one row per node, making it easy to inspect, filter, or pipe into other functions.

Usage

taxo_path(taxon_a, taxon_b, verbose = FALSE)

Arguments

taxon_a	A character string giving the first taxon name.
taxon_b	A character string giving the second taxon name.
verbose	Logical. If TRUE, prints progress messages. Default FALSE.

Value

A data frame of class "taxodist_path" with columns:

node

Character. The clade or taxon name at this step.

depth

Integer. The depth of this node in the full lineage of its side (or the shared lineage for the MRCA).

direction

Character. One of "a" (ascending from taxon A to MRCA), "mrca" (the shared ancestor), or "b" (descending from MRCA to taxon B).

Returns NULL if either taxon cannot be found.

See Also

mrca(), shared_clades(), compare_lineages()

Examples

taxo_path("Tyrannosaurus", "Velociraptor")
taxo_path("Tyrannosaurus", "Homo")

---

Search The Taxonomicon for a taxon name

Description

Queries The Taxonomicon database and returns a data frame of all available biological entries matching the search string. This is particularly useful for exploring homonyms, historical ranks, or taxonomic synonyms before computing distances.

Usage

taxo_search(taxon, verbose = FALSE)

Arguments

taxon	A character string giving the taxon name to search for.
verbose	Logical. If TRUE, prints status messages. Default FALSE.

Value

A data frame of class "data.frame" with columns:

id

Character. The numeric Taxonomicon ID.

name

Character. The full taxon description, including rank and author.

Returns NULL if no matches are found.

See Also

get_lineage(), taxo_distance()

Examples

taxo_search("Bacteria")
taxo_search("Nereis")
taxo_search("Tyrannosaurus")

---

Reference Taxonomic Dataset (taxobase)

Description

A pre-computed dataset containing 50 taxonomic clades spanning across the tree of life, fetched from The Taxonomicon. This provides a offline fallback containing lineages, distance matrices, and search queries for demonstrating the package.

Usage

data(taxobase)

Format

A structured list containing the following pre-computed components:

taxa

Character vector of 1,000 candidate taxonomic genera.

found_taxa

Character vector of verified clades found in The Taxonomicon.

coverage

Named logical vector indicating database presence of each taxon.

matrix

A pre-computed taxonomic 'dist' object for verified clades.

pairwise

A pre-computed distance list between Tyrannosaurus and Homo.

lineage_homo

Full taxonomy tree structure list for 'Homo'.

lineage_tyrannosaurus

Full taxonomy tree structure list for 'Tyrannosaurus'.

closest

Dataframe demonstrating the closest relative query.

filter

Character vector filtering verified taxa down to Theropoda.

search

Reference search result dataset for the term 'Bacteria'.

Source

http://taxonomicon.taxonomy.nl

Examples

data(taxobase)
length(taxobase$found_taxa)
head(labels(taxobase$matrix))

---