One value per sample: the log of the summed abundance of the numerator
features over that of the denominator features, as Qurro plots it.
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 ratio.
- numerator, denominator
The features on the top and the bottom of the ratio, each given as feature names, (1-based) feature indices, or a logical vector with one value per feature. Both are required, each must select at least one feature, and they must not share any. The two may use different forms (names for one, indices for the other).
- 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 selected value before summing, so \(r c\) is added to a numerator of \(r\) features.
0(the default) adds nothing;NULLapplies the rule of the other log-ratio functions (half the smallest non-zero value of the whole table, with a warning, when it has zeros). See Zeros.
Value
A numeric vector with one value per sample, in the order of
counts and named after the samples (unnamed if they have no names),
whatever the margin. Larger values mean relatively more of the
numerator. Attributes:
method:'log_ratio'.numerator,denominator: the selected features' names (their indices when the features have no names), in the order ofcounts.pseudocount: the pseudocount used (0for none).
The vector drops straight into metadata (data$ratio <- log_ratio(...))
and into any test or fit that takes a per-sample variable, such as
envfit() or mantel().
Details
For a sample \(x\), numerator features \(N\) and denominator features
\(D\), the log ratio is
$$\log\frac{\sum_{i \in N} (x_i + c)}{\sum_{j \in D} (x_j + c)}$$
with \(c\) the pseudocount (natural logs). With one feature on each
side, this is the log ratio of two features, and equals the matching
balance() divided by \(\sqrt{1/2}\).
Ratios between features can be interpreted without knowing each sample's
total load: if the ratio of A to B goes up, it went up whatever happened
to the total (the "reference frames" of Morton et al. 2019). Qurro
(Fedarko et al. 2020) is a tool for choosing the numerator and
denominator interactively from feature rankings; this function computes
the same log ratio (log(Num_Sum / Denom_Sum) in Qurro's qarcoal) for
use in R.
Log ratio or balance? Sums are robust to zeros in single features and
easy to explain ("the log of the ratio of total Firmicutes to total
Bacteroidetes"), but a sum is dominated by its most abundant features.
balance() uses geometric means instead: every feature counts equally,
it is a coordinate of the isometric log-ratio geometry the CoDa theory is
built on, and its scale makes balances of different sizes comparable;
but a zero in any one of its features needs replacing first.
Zeros
Zeros in single features are harmless as long as each sum is positive,
so no pseudocount is needed in almost every case, and none is used by
default (unlike the other log-ratio functions, whose default is
NULL). A sample whose numerator or denominator sums to 0 has no
defined ratio: its value is NA, with one warning naming such samples.
(Qurro drops those samples; ecodive keeps their place, so the result
lines up with counts.) A positive pseudocount gives them a value.
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.
References
Morton, J. T., Marotz, C., Washburne, A., et al. (2019). Establishing microbial composition measurement standards with reference frames. Nature Communications, 10, 2719.
Fedarko, M. W., Martino, C., Morton, J. T., et al. (2020). Visualizing 'omic feature rankings and log-ratios using Qurro. NAR Genomics and Bioinformatics, 2, lqaa023.
Examples
# Oral streptococci and Haemophilus against skin taxa
r <- log_ratio(
ex_counts,
numerator = c('Streptococcus', 'Haemophilus'),
denominator = c('Propionibacterium', 'Staphylococcus', 'Corynebacterium') )
r
#> Saliva Gums Nose Stool
#> 5.834811 6.086775 -3.714588 0.000000
#> attr(,"method")
#> [1] "log_ratio"
#> attr(,"numerator")
#> [1] "Streptococcus" "Haemophilus"
#> attr(,"denominator")
#> [1] "Corynebacterium" "Propionibacterium" "Staphylococcus"
#> attr(,"pseudocount")
#> [1] 0
# The same, by index; zero sums give NA
log_ratio(ex_counts, c(1, 4), c(3, 5, 6))
#> Saliva Gums Nose Stool
#> 5.834811 6.086775 -3.714588 0.000000
#> attr(,"method")
#> [1] "log_ratio"
#> attr(,"numerator")
#> [1] "Streptococcus" "Haemophilus"
#> attr(,"denominator")
#> [1] "Corynebacterium" "Propionibacterium" "Staphylococcus"
#> attr(,"pseudocount")
#> [1] 0
suppressWarnings(log_ratio(ex_counts, 2, 6))
#> Saliva Gums Nose Stool
#> NA 1.386294 -4.770685 6.415097
#> attr(,"method")
#> [1] "log_ratio"
#> attr(,"numerator")
#> [1] "Bacteroides"
#> attr(,"denominator")
#> [1] "Staphylococcus"
#> attr(,"pseudocount")
#> [1] 0
