dist_calc: Calculate distances between pairs of samples in phyloseq...

In david-barnett/microViz: Microbiome Data Analysis and Visualization

Calculate distances between pairs of samples in phyloseq object

Description

Can compute various sample-sample distances using the microbiota composition of your samples:

• Bray Curtis ('bray') or any other ecological distance from phyloseq::distance() / vegan::vegdist()

• UniFrac distances (using the GUniFrac package)

  • generalised: 'gunifrac' (optionally set weighting alpha in gunifrac alpha)

  • unweighted: 'unifrac'

  • weighted: 'wunifrac'

• Aitchison distance (Euclidean distance after centered log ratio transform clr, see details)

• Euclidean distance

Use dist_calc with psExtra output of tax_transform (or tax_agg). It returns a psExtra object containing the phyloseq and the name of the distance used in addition to the distance matrix itself. The resulting object is intended to be piped into ord_calc or dist_permanova functions. Alternatively you can directly access the distance matrix with dist_get().

Usage

dist_calc(data, dist = "bray", gunifrac_alpha = 0.5, ...)

Arguments

data	psExtra object, e.g. output from tax_transform()
dist	name of distance to calculate between pairs of samples
gunifrac_alpha	setting alpha value only relevant if gunifrac distance used
...	optional distance-specific named arguments passed to phyloseq::distance()

Value

psExtra object including distance matrix and name of distance used

Aitchison distance note

You should EITHER:

1. skip the dist_calc function and call ord_calc(method = "PCA") directly on an object with taxa transformed with tax_transform(trans = "clr")

2. pass an object with untransformed (or 'identity' transformed) taxa to the data argument of dist_calc() and specify dist = "aitchison".

If ordination plots with taxon loading vectors are desired, users require option 1. If the distance matrix is required for permanova, users require option 2.

Binary Jaccard distance note

Jaccard distance can be computed on abundances, but often in microbiome research it is the Binary Jaccard distance that is desired. So remember to first perform a "binary" transformation with tax_transform("binary"), OR pass an additional argument to dist_calc("jaccard", binary = TRUE)

See Also

tax_transform for the function to use before dist_calc

ord_calc

ord_plot

dist_permanova

phyloseq::distance

vegan::vegdist

Examples

# bray curtis distance on genera-level features
data("dietswap", package = "microbiome")
bc <- dietswap %>%
  tax_agg("Genus") %>%
  dist_calc("bray")
bc
class(bc)

# gunifrac distance using phyloseq input
data("esophagus", package = "phyloseq")
gunifrac <- esophagus %>%
  dist_calc("gunifrac") %>%
  dist_get()
class(gunifrac)

david-barnett/microViz documentation built on April 17, 2025, 4:25 a.m.