Euclidean distances between samples' PhILR coordinates, with the weights that Silverman et al. (2017) recommend: a compositional, phylogenetic beta diversity.
Usage
philr_distance(
counts,
tree = NULL,
margin = 1L,
pseudocount = NULL,
pairs = NULL,
clust = NULL,
cpus = n_cpus()
)Arguments
- counts
A numeric matrix of counts or proportions (samples \(\times\) features, see
margin), or an object of one of the types in Input Types. Its features must have names, matched to the tips oftree. The part weights assume counts.- tree
A
phyloobject with branch lengths, whose tips include every feature ofcounts, orNULLto use the tree insidecounts(a phyloseq, rbiom or TreeSummarizedExperiment object, orattr(counts, 'tree')).- margin
The margin containing samples.
1if samples are rows,2if samples are columns. Ignored whencountsis a special object class (e.g.phyloseq). Default:1- pseudocount
Added to every value before taking logs.
NULL(the default) adds nothing whencountshas no zeros, and otherwise uses half the smallest non-zero value, with a warning. See Pseudocount.- 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) orFALSEto keep them in their input order, or one ofstats::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 ofpcoa(). Clustering reorders the samples of the result, with their labels (samples without names are labelled with their positions in the input): itsorderattribute gives each one's position in the input, so thatmeta[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 byorder, or matched by name. The matrix'sdisplaylist keepsclust(FALSEas"none"; see ecodive_display), whichplot.ecodive_dist()follows: withNULLit clusters the samples for the heatmap ("average"), and with"none"it keeps their order.clustneeds every distance, so it cannot be used withpairs.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 anycpus.
Value
A distance matrix: a dist object of class c("ecodive_dist", "dist"), as every metric function returns (see beta_div()).
Details
The distance between samples \(x\) and \(y\) is
$$\sqrt{\sum_i \left(x^*_i - y^*_i\right)^2},$$
where \(x^*\) are the philr() coordinates of \(x\) with part weights
'enorm.x.gm.counts' and ILR weights 'blw.sqrt' (Silverman et al.
2017, Methods), so that
philr_distance(x, tree) ==
euclidean(philr(x, tree, part_weights = 'enorm.x.gm.counts', ilr_weights = 'blw.sqrt'))For other weightings, use euclidean(philr(x, tree, ...)). With uniform
weights, PhILR distances are Aitchison distances (aitchison()): the
weights are what make them phylogenetic. The part weights are computed
from all the samples, so adding or removing a sample changes the
distances between the others. pairs limits which distances are
computed, not the samples used.
The tree is handled as philr() handles it: tips that aren't features
are dropped, and polytomies are resolved, with a warning (see
The tree in philr()). It needs branch lengths.
Input Types
The counts parameter is designed to accept a simple numeric matrix, but
seamlessly supports objects from the following biological data packages:
phyloseqrbiomSummarizedExperimentTreeSummarizedExperiment
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.
Pseudocount
Logs of zero are undefined, so zeros need replacing first. The
pseudocount is added to every value (not only to zeros), as in
normalize(norm = 'clr'). With pseudocount = NULL (the default), no
pseudocount is used when counts has no zeros; otherwise half the
smallest non-zero value is, with a warning. To avoid a pseudocount,
replace the zeros first with replace_zeros(): its result has none.
The choice of pseudocount is not neutral: it can distort the results,
especially for sparse tables. See aitchison() for references.
References
Silverman, J. D., Washburne, A. D., Mukherjee, S., & David, L. A. (2017). A phylogenetic transform enhances analysis of compositional microbiota data. eLife, 6, e21887. doi:10.7554/eLife.21887
See also
philr(), beta_div(), aitchison(), weighted_unifrac()
Other Phylogenetic metrics:
faith(),
generalized_unifrac(),
normalized_unifrac(),
unweighted_unifrac(),
variance_adjusted_unifrac(),
weighted_unifrac()
Examples
philr_distance(ex_counts, tree = ex_tree, pseudocount = 1)
#> # A dist: 4 samples (lower triangle)
#> # PhILR Distance
#> Saliva Gums Nose
#> Gums 45.4
#> Nose 175 173
#> Stool 281 263 183
#> # Attributes: method
# The same, from beta_div()
d <- beta_div(ex_counts, 'philr', tree = ex_tree, pseudocount = 1)
