Skip to contents

A unified UniFrac distance that balances the weight of abundant and rare lineages.

Usage

generalized_unifrac(
  counts,
  tree = NULL,
  alpha = 0.5,
  margin = 1L,
  pairs = NULL,
  clust = NULL,
  cpus = n_cpus()
)

Arguments

counts

A numeric matrix of count data (samples \(\times\) features). Typically contains absolute abundances (integer counts), though proportions are also accepted.

tree

A phylo-class object representing the phylogenetic tree for the OTUs in counts. The OTU identifiers given by colnames(counts) must be present in tree. Can be omitted if a tree is embedded with the counts object or as attr(counts, 'tree').

alpha

How much weight to give to relative abundances; a value between 0 and 1, inclusive. Setting alpha=1 is equivalent to normalized_unifrac().

margin

The margin containing samples. 1 if samples are rows, 2 if samples are columns. Ignored when counts is a special object class (e.g. phyloseq). Default: 1

pairs

Which combinations of samples should distances be calculated for? The default value (NULL) calculates all-vs-all. Provide a numeric or logical vector specifying positions in the distance matrix to calculate. See examples.

clust

Whether and how to cluster the samples (rows and columns) before returning the distance matrix: NULL (the default) or FALSE to keep them in their input order, or one of stats::hclust()'s linkage methods, "average" (UPGMA), "complete", "single", "ward.D", "ward.D2", "mcquitty" (WPGMA), "median" or "centroid", or "pcoa" to order them along the first axis of pcoa(). Clustering reorders the samples of the result, with their labels (samples without names are labelled with their positions in the input): its order attribute gives each one's position in the input, so that meta[attr(d, "order"), ] lines metadata up with them. ecodive's ordinations and tests put the samples back in their input order before analysing them, so give them metadata in its usual order. Other packages see the reordered matrix: give them metadata reordered by order, or matched by name. The matrix's display list keeps clust (FALSE as "none"; see ecodive_display), which plot.ecodive_dist() follows: with NULL it clusters the samples for the heatmap ("average"), and with "none" it keeps their order. clust needs every distance, so it cannot be used with pairs. rho_p()'s similarities are clustered as \(1 - \rho_p\).

cpus

How many parallel processing threads should be used. The default, n_cpus(), is the CPU cores this R process may use, within any limits set on it. Results are the same for any cpus.

Details

The Generalized UniFrac distance is defined as: $$\frac{\sum_{i=1}^{n} L_i(P_i + Q_i)^{\alpha}\left|\frac{P_i - Q_i}{P_i + Q_i}\right|}{\sum_{i=1}^{n} L_i(P_i + Q_i)^{\alpha}}$$

Where:

  • \(n\) : The number of branches in the tree.

  • \(L_i\) : The length of the \(i\)-th branch.

  • \(P_i\), \(Q_i\) : The proportion of the community descending from branch \(i\) in sample P and Q.

  • \(\alpha\) : A scalable weighting factor.

Parameter: alpha

The alpha parameter controls the weight given to abundant lineages. \(\alpha = 1\) corresponds to Weighted UniFrac, while \(\alpha = 0\) corresponds to Unweighted UniFrac.

Input Types

The counts parameter is designed to accept a simple numeric matrix, but seamlessly supports objects from the following biological data packages:

  • phyloseq

  • rbiom

  • SummarizedExperiment

  • TreeSummarizedExperiment

For large datasets, standard matrix operations may be slow. See vignette('performance') for details on using optimized formats (e.g. sparse matrices) and parallel processing.

References

Chen, J., Bittinger, K., Charlson, E. S., Hoffmann, C., Lewis, J., Wu, G. D., ... & Li, H. (2012). Associating microbiome composition with environmental covariates using generalized UniFrac distances. Bioinformatics, 28(16), 2106-2113. doi:10.1093/bioinformatics/bts342

Examples

    generalized_unifrac(ex_counts, tree = ex_tree, alpha = 0.5)
#> # A dist: 4 samples (lower triangle)
#> # Generalized UniFrac (GUniFrac)
#>       Saliva  Gums  Nose
#> Gums   0.447
#> Nose   0.822 0.761
#> Stool  0.973 0.978 0.973
#> # Attributes: method