The log of every feature's abundance relative to one chosen feature, the
denominator: Aitchison's additive log ratio (alr).
Usage
alr(counts, denominator, margin = 1L, pseudocount = NULL, cpus = n_cpus())Arguments
- counts
A numeric matrix of non-negative abundances (samples \(\times\) features), or any of the objects listed under Input Types. Counts, proportions, and the output of a zero replacement are all accepted: each sample's scale cancels out of the log ratios.
- denominator
The feature to divide by: its name, or its (1-based) index among the features, or a logical vector with one
TRUE. Required. Choose a feature that is present in every sample and abundant and stable across them, since every coordinate is relative to it.- 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.- 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, in the
orientation of counts: samples \(\times\) coordinates for margin = 1, coordinates \(\times\) samples for margin = 2 (and for a single
sample given as a vector). Sample names are kept. Each coordinate is
named after its numerator feature, in the order of counts; features
without names give alr1, alr2, ..., numbered by their position in
counts (so denominator = 2 of 4 gives alr1, alr3, alr4).
Attributes:
method:'alr'.denominator: the denominator feature's name, or its index when the features have no names.pseudocount: the pseudocount used (0for none).
Details
For a sample \(x\) of \(D\) features and denominator \(x_d\),
$$\mathrm{alr}(x) = \left[\log\frac{x_j + c}{x_d + c}\right]_{j \neq d}$$
with \(c\) the pseudocount (natural logs). The coordinates are easy to
interpret (everything relative to one feature) and are what multinomial
regression models use, but the transform is not an isometry: Euclidean
distances between alr coordinates are not Aitchison distances. For
distances, use aitchison(); for orthonormal coordinates, ilr(). The
centered log ratio is normalize(counts, 'clr') (or norm = 'clr' in any
function that takes norm).
alr(x + c, d) here equals scikit-bio's alr(x + c, ref_idx = d - 1)
exactly. scikit-bio defaults to the first feature and compositions::alr()
to the last: ecodive has no default, because the choice shapes every
coordinate.
The result feeds straight into pca(), rda(), lda(), envfit() and
euclidean(), which take negative values with norm = 'none'.
Same names in other packages: compositions::alr() (the last part as
denominator) and robCompositions::addLR() compute the same transform.
Whichever package was attached last masks the other's alr(); write
ecodive::alr() 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
Aitchison, J. (1986). The Statistical Analysis of Compositional Data. Chapman & Hall.
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
See also
ilr(), normalize() ('clr' and 'rclr'), aitchison()
Examples
# Relative to the first feature
x <- alr(ex_counts, denominator = 1, pseudocount = 1)
x[1:3, 1:3]
#> Bacteroides Corynebacterium Haemophilus
#> Saliva -3.995138 -5.093750 0.1047468
#> Gums -5.067646 -6.677083 -2.1997466
#> Nose -2.036882 3.077112 -2.0368819
attr(x, 'denominator')
#> [1] "Streptococcus"
# The same as the log ratios themselves
all.equal(
unname(x[, 1]),
unname(log((ex_counts[, 2] + 1) / (ex_counts[, 1] + 1))) )
#> [1] TRUE
