Statistical Applications of taxodist"

In taxodist: Taxonomic Distance and Phylogenetic Lineage Computation

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
library(taxodist)

The taxodist distance matrix is a standard dist object and integrates directly with the R ecosystem for multivariate analysis. This vignette shows how to use it alongside vegan and ape for ecological and phylogenetic analyses. All examples use a set of threatened mammals from Brazil spanning five broad taxonomic groups.

---

Example dataset: threatened mammals of Brazil

taxa_brazil <- c(
  "Priodontes", "Myrmecophaga", "Chrysocyon", "Tapirus", "Didelphis",
  "Leontopithecus", "Brachyteles",
  "Panthera", "Pteronura", "Puma",
  "Sotalia", "Pontoporia",
  "Trichechus", "Mazama", "Blastocerus"
)

The dataset covers xenarthrans (Priodontes, Myrmecophaga), a marsupial (Didelphis), ungulates (Tapirus, Mazama, Blastocerus), primates (Leontopithecus, Brachyteles), carnivores (Chrysocyon, Panthera, Pteronura, Puma), cetaceans (Sotalia, Pontoporia), and a sirenian (Trichechus).

The pairwise distance matrix is computed with a single call. Lineages are cached after the first retrieval, so subsequent analyses on the same taxa are instantaneous.

library(taxodist)
mat <- distance_matrix(taxa_brazil)
print(mat)
#>                Priodontes Myrmecophaga Chrysocyon    Tapirus  Didelphis
#> Myrmecophaga   0.01639344
#> Chrysocyon     0.01694915   0.01694915
#> Tapirus        0.01694915   0.01694915 0.01587302
#> Didelphis      0.01754386   0.01754386 0.01754386 0.01754386
#> Leontopithecus 0.01694915   0.01694915 0.01666667 0.01666667 0.01754386
#> Brachyteles    0.01694915   0.01694915 0.01666667 0.01666667 0.01754386
#> Panthera       0.01694915   0.01694915 0.01492537 0.01587302 0.01754386
#> Pteronura      0.01694915   0.01694915 0.01470588 0.01587302 0.01754386
#> Puma           0.01694915   0.01694915 0.01492537 0.01587302 0.01754386
#> Sotalia        0.01694915   0.01694915 0.01587302 0.01562500 0.01754386
#> Pontoporia     0.01694915   0.01694915 0.01587302 0.01562500 0.01754386
#> Trichechus     0.01666667   0.01666667 0.01694915 0.01694915 0.01754386
#> Mazama         0.01694915   0.01694915 0.01587302 0.01562500 0.01754386
#> Blastocerus    0.01694915   0.01694915 0.01587302 0.01562500 0.01754386

Didelphis shows the largest distances to all other taxa (0.01754), consistent with the early divergence of marsupials from placental mammals. Carnivores (Panthera, Pteronura, Puma) show smaller distances among themselves, reflecting a more recent common ancestor within Carnivora.

---

Phylogenetic tree with ape

taxo_cluster() performs hierarchical clustering on the distance matrix and returns an object that ape can convert directly to a phylo tree for publication-quality visualisation.

library(ape)

cl   <- taxo_cluster(taxa_brazil)
tree <- ape::as.phylo(cl$hclust)

plot(tree,
     main      = "Threatened Mammals of Brazil",
     cex       = 0.85,
     tip.color = "gray20")

The phylo object is fully compatible with all ape tree manipulation and plotting functions, including nodelabels(), edgelabels(), and export to Newick format via write.tree().

ape::write.tree(tree, file = "taxa_brazil.nwk")

---

Taxonomic diversity with vegan

Clarke and Warwick indices (taxondive)

vegan::taxondive() computes a family of taxonomic diversity indices (Clarke and Warwick 1998, 2001) from a community matrix and a taxonomic distance matrix. These indices capture not just species richness but how distantly related the species in a community are: a community of closely related species scores lower than one with the same richness but spanning multiple orders.

The function expects a community matrix (sites x species) and the dist object from distance_matrix(). Here we define three hypothetical communities, each dominated by one broad taxonomic group.

set.seed(123)
library(vegan)

comm <- matrix(c(
  1, 1, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,   # xenarthrans + marsupial
  0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0,   # primates + carnivores
  0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1    # cetaceans + sirenian + ungulates
), nrow = 3, byrow = TRUE)

colnames(comm) <- taxa_brazil
rownames(comm) <- c("community_A", "community_B", "community_C")

vegan::taxondive(comm, mat)
#>               Species      Delta       Delta*     Lambda+     Delta+     S Delta+
#> community_A  3.0000e+00  1.7160e-02  1.7160e-02  2.9410e-07  1.7160e-02   0.0515
#> community_B  5.0000e+00  1.5905e-02  1.5905e-02  8.8325e-07  1.5905e-02   0.0795
#> community_C  5.0000e+00  1.5750e-02  1.5750e-02  1.1834e-06  1.5750e-02   0.0788
#> Expected                -9.9265e-02  1.6544e-02              1.6457e-02         

The key indices are:

Delta ($\Delta$): mean taxonomic distance between all pairs of species in the community.

Delta ($\Delta^$): mean pairwise distance excluding self-comparisons; comparable across communities of different sizes.

Delta+ ($\Delta^+$): mean pairwise distance weighted by species abundances. For presence-absence data this equals $\Delta^*$.

Lambda+ ($\Lambda^+$): variance in taxonomic distances, measuring how evenly a community spans the taxonomic tree.

community_A, dominated by xenarthrans and a marsupial, scores the highest $\Delta$ (0.01673), reflecting deeper divergences among its members. community_B (primates and carnivores) scores the lowest (0.01591), as its members share more recent common ancestors within Placentalia.

---

Mantel test with vegan

The Mantel test assesses the correlation between two distance matrices by permutation. A typical application is testing whether taxonomic distance correlates with geographic distance, a signature of phylogeographic structure.

Here we use simulated coordinates for illustration. In practice, replace coords with observed latitude and longitude values.

set.seed(42)
coords <- matrix(rnorm(30), ncol = 2)
rownames(coords) <- taxa_brazil
geo_dist <- dist(coords)

vegan::mantel(mat, geo_dist)
#> Mantel statistic based on Pearson's product-moment correlation
#>
#> Call:
#> vegan::mantel(xdis = mat, ydis = geo_dist)
#>
#> Mantel statistic r: -0.0569
#>       Significance: 0.653
#>
#> Upper quantiles of permutations (null model):
#>   90%   95% 97.5%   99% 
#> 0.188 0.237 0.272 0.336 
#> Permutation: free
#> Number of permutations: 999

The non-significant result (r = -0.27, p = 0.972) is expected with random coordinates. For non-normal distance distributions, "spearman" is more robust than the default "pearson".

vegan::mantel(mat, geo_dist, method = "spearman", permutations = 9999)
#> Mantel statistic based on Spearman's rank correlation rho 
#>
#> Call:
#> vegan::mantel(xdis = mat, ydis = geo_dist, method = "spearman",
#>     permutations = 9999)
#>
#> Mantel statistic r: -0.07405
#>       Significance: 0.672
#>
#> Upper quantiles of permutations (null model):
#>   90%   95% 97.5%   99%
#> 0.189 0.244 0.293 0.353 
#> Permutation: free
#> Number of permutations: 9999

---

PERMANOVA with vegan

PERMANOVA (Anderson 2001) tests whether groups of taxa differ significantly in taxonomic distance space. It partitions total variance in the distance matrix into within-group and between-group components and assesses significance by permutation, with no assumption of multivariate normality.

groups <- c(
  "xenarthra", "xenarthra", "carnivore", "ungulate",  "marsupial",
  "primate",   "primate",
  "carnivore", "carnivore", "carnivore",
  "cetacean",  "cetacean",
  "sirenian",  "ungulate",  "ungulate"
)

vegan::adonis2(mat ~ groups)
#> Permutation test for adonis under reduced model
#> Permutation: free
#> Number of permutations: 999
#>
#> vegan::adonis2(formula = mat ~ groups)
#>          Df  SumOfSqs      R2      F Pr(>F)
#> Model     6 0.00100049 0.52646 1.4823  0.001 ***
#> Residual  8 0.00089992 0.47354  
#> Total    14 0.00190041 1.00000   
#> ---
#> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

The taxonomic grouping explains $49.6\%$ of the total variance in the distance matrix ($\text{R}^2 = 0.496$, $\text{p} = 0.001$). This confirms that the broad mammalian orders occupy distinct regions of taxonomic distance space, consistent with their deep evolutionary divergences.

For pairwise comparisons between groups after a significant PERMANOVA, see pairwise.adonis2() in the pairwiseAdonis package.

---

A complete workflow

The following script chains all steps from taxon names to multivariate analysis.

library(taxodist)
library(vegan)
library(ape)

# 1. define taxa
taxa_brazil <- c(
  "Priodontes", "Myrmecophaga", "Chrysocyon", "Tapirus", "Didelphis",
  "Leontopithecus", "Brachyteles",
  "Panthera", "Pteronura", "Puma",
  "Sotalia", "Pontoporia",
  "Trichechus", "Mazama", "Blastocerus"
)

# 2. compute distance matrix
mat <- distance_matrix(taxa_brazil)

# 3. hierarchical clustering and phylo plot
cl   <- taxo_cluster(taxa_brazil)
tree <- ape::as.phylo(cl$hclust)
plot(tree, main = "Threatened Mammals of Brazil", cex = 0.85)

# 4. PCoA ordination
ord <- taxo_ordinate(mat)
plot(ord, main = "PCoA: Taxonomic Distance Space")

# 5. PERMANOVA
groups <- c(
  "xenarthra", "xenarthra", "carnivore", "ungulate",  "marsupial",
  "primate",   "primate",
  "carnivore", "carnivore", "carnivore",
  "cetacean",  "cetacean",
  "sirenian",  "ungulate",  "ungulate"
)
vegan::adonis2(mat ~ groups)

---

References

Anderson, M.J. (2001). A new method for non-parametric multivariate analysis of variance. Austral Ecology, 26, 32--46.

Clarke, K.R. and Warwick, R.M. (1998). A taxonomic distinctness index and its statistical properties. Journal of Applied Ecology, 35, 523--531.

Clarke, K.R. and Warwick, R.M. (2001). A further biodiversity index applicable to species lists: variation in taxonomic distinctness. Marine Ecology Progress Series, 216, 265--278.

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

taxodist documentation built on May 6, 2026, 1:06 a.m.