Silverman et al.'s PhILR coordinates: an isometric log-ratio transform whose balances follow a phylogeny. Each internal node of the tree gives one coordinate, the log ratio of its two child clades' (weighted) geometric means, so every coordinate has an evolutionary meaning: "this clade against its sister clade".
Usage
philr(
counts,
tree = NULL,
margin = 1L,
pseudocount = NULL,
part_weights = "uniform",
ilr_weights = "uniform",
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. Counts, proportions and the output ofreplace_zeros()are all accepted, with one caveat: the'gm.counts'part weights assume counts.- tree
A
phyloobject whose tips include every feature ofcounts, orNULLto use the tree insidecounts(a phyloseq, rbiom or TreeSummarizedExperiment object, orattr(counts, 'tree')). See The 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.- part_weights
The weights \(p_j\) of the features (philr's
part.weights), which set the reference measure of the simplex. One of'uniform'(the default): all 1, the usual ilr;'gm.counts': each feature's geometric mean over the samples (ofcounts + pseudocount);'enorm': the Euclidean norm of each feature's values over the samples, after closing them to sum to 1 (so that a feature found in only a few samples gets a weight near 1, and one spread evenly over \(n\) samples gets \(1/\sqrt{n}\));'anorm': the Aitchison norm of each feature's values over the samples, \(\sqrt{\sum_k (\log x_{kj} - \overline{\log x_j})^2}\);'enorm.x.gm.counts'and'anorm.x.gm.counts': products of the two;a vector of positive numbers, one per feature, named by feature (or in the order of the features of
counts).
Names may also be written with underscores (
'gm_counts'). The weights computed fromcountsdepend on every sample, so one sample's coordinates depend on the others.- ilr_weights
The weights \(f_i\) of the coordinates (philr's
ilr.weights), which scale each balance. One of'uniform'(the default): all 1;'blw': the sum of the node's two child branch lengths;'blw.sqrt': its square root;'mean.descendants': the sum of the two child branch lengths plus, for each child, its mean distance to its tips;a vector of non-negative numbers, one per coordinate, named by coordinate (or in the order of the coordinates).
For the branch-length weights, zero-length branches to tips first get the smallest positive branch length of the tree, as in philr. They need
treeto have branch lengths.- 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 dense numeric matrix of the \(D - 1\) coordinates, one per
internal node of the tree, in the orientation of counts: samples
\(\times\) coordinates for margin = 1, coordinates \(\times\)
samples for margin = 2. Sample names are kept. Coordinates are named
by the tree's node labels when every node has a distinct one (nodes
added to resolve a polytomy at node "X" get "X.1", "X.2", ...),
and otherwise n1, n2, ..., in column order. Attributes:
method:'philr'.part_weights: the part weights used, named by feature, in the order of the features ofcounts.ilr_weights: the ILR weights used, named by coordinate.tree: the tree used, as aphyloobject (see The tree). Its internal nodes are numbered and labelled in column order (node \(D + k\) is coordinate \(k\)), and for each node, its first child intree$edgeis the numerator ("+") clade.pseudocount: the pseudocount used (0for none).
These are what philr's return.all = TRUE gives as p, ilr.weights
and (through the tree) sbp. Its contrast matrix V is not kept: it
has \(D (D - 1)\) entries.
Details
For a sample \(x\) (with the pseudocount added) and part weights \(p\), write \(y_j = x_j / p_j\). At an internal node with clades \(A\) (its first child, the numerator) and \(B\) (its second), let \(n_A = \sum_{j \in A} p_j\) and \(\log g_A = \sum_{j \in A} p_j \log y_j / n_A\) (and likewise for \(B\)). The node's coordinate is $$f \sqrt{\frac{n_A n_B}{n_A + n_B}}\,\left(\log g_A - \log g_B\right),$$ with \(f\) its ILR weight (Silverman et al. 2017, Methods). It is computed in \(O(D)\) per sample, by summing over each clade from the tips up, without forming the \(D \times (D - 1)\) basis.
With uniform weights the coordinates are an ordinary ilr: they equal
ilr(counts, basis = sbp) for the tree's sequential binary partition, and
euclidean(philr(x, tree)) is aitchison(x) (with the same
pseudocount), as for any orthonormal basis. It is the weights that make
distances phylogenetic: philr_distance() uses the paper's.
The coordinates feed straight into pca(), rda(), lda(), envfit()
and euclidean(), which take negative values with norm = 'none'.
philr(x, tree, pseudocount = c, part_weights = pw, ilr_weights = iw)
equals philr 1.28.0's philr(x, tree, part.weights = pw, ilr.weights = iw, pseudocount = c) to rounding, for every weighting and for a binary tree
whose tips are the features of x.
The tree
PhILR needs a rooted binary tree whose tips are the features. tree is
made one in three steps (the result is the tree attribute):
Tips that aren't features of
countsare dropped, and so are the internal nodes left without any. Every feature must be a tip.Nodes left with one child are removed, their branch length added to their child's (a root with one child is dropped), as
ape::drop.tip()does.Polytomies are resolved, with a warning: a node with children \(c_1, \dots, c_k\), \(k > 2\), keeps \(c_1\) and gets a new child node, joined by a zero-length branch, that holds \(c_2, \dots, c_k\) (and so on), as
ape::multi2di(random = FALSE)does. An unrooted tree (three children at the root) is resolved the same way. Results then depend on the order of the children: to choose the resolution, resolve the tree first.
Coordinates are in the order of the internal nodes' numbers in tree
(the root first), or, when a step changed the tree, in preorder of the
new tree (which is also the order of ape::multi2di()'s and
ape::drop.tip()'s numbering). Branch lengths are needed only for the
branch-length ILR weights; they must be non-negative. A root edge is
ignored.
Same names in other packages: philr::philr() computes the same
transform, with the same orientation and order. Whichever package was
attached last masks the other's philr(); write ecodive::philr() to be
sure.
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.
Machine learning
Log-ratio transforms (clr, rclr, alr, ilr, PhILR) serve interpretation
and compositional geometry; don't expect them to improve prediction.
With random forests predicting 65 metadata variables in four datasets,
Yerke et al. (2024) found that alr, clr and ilr (PhILR) "performed
generally slightly worse or only as well as compositionally naïve
transformations", and relative abundances did best, by a small margin.
Compare with norm = 'percent' (see normalize()) before choosing a
log-ratio predictor table.
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
Egozcue, J. J., & Pawlowsky-Glahn, V. (2016). Changing the reference measure in the simplex and its weighting effects. Austrian Journal of Statistics, 45(4), 25–44. doi:10.17713/ajs.v45i4.126
Yerke, A., Fry Brumit, D., & Fodor, A. A. (2024). Proportion-based normalizations outperform compositional data transformations in machine learning applications. Microbiome, 12, 45. doi:10.1186/s40168-023-01747-z
Examples
x <- philr(ex_counts, tree = ex_tree, pseudocount = 1)
dim(x)
#> [1] 4 5
x[1:3, 1:4]
#> n1 n2 n3 n4
#> Saliva 1.965104 2.899056 2.200302 3.601825
#> Gums 1.186504 2.027911 3.338542 4.231282
#> Nose -4.604698 0.000000 -1.569240 -1.649373
# With uniform weights, distances are Aitchison distances
all.equal(
as.vector(euclidean(x)),
as.vector(aitchison(ex_counts, pseudocount = 1)) )
#> [1] TRUE
# The paper's weights
x <- philr(
ex_counts, tree = ex_tree, pseudocount = 1,
part_weights = 'enorm.x.gm.counts', ilr_weights = 'blw.sqrt' )
head(attr(x, 'ilr_weights'))
#> n1 n2 n3 n4 n5
#> 3.605551 10.583005 4.898979 5.385165 6.082763
