The proportionality coefficient \(\rho_p\) of Erb & Notredame (2016),
propr's default "rho": a correlation-like measure of how close each
pair of features is to keeping a constant ratio. 1 means perfectly
proportional.
Usage
rho_p(
counts,
margin = 1L,
denominator = NULL,
pseudocount = NULL,
clust = 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
replace_zeros()are all accepted: each sample's scale cancels out of the log ratios. Pairs are taken between the features (the columns whenmargin = 1), and the variance is over the samples.- margin
The margin containing samples.
1if samples are rows,2if samples are columns. Ignored whencountsis a special object class (e.g.phyloseq). Default:1- denominator
The reference that each feature's log abundance is taken relative to, for the variances \(\mathrm{var}(z_i)\).
NULL(the default) uses the centered log ratio (clr): each sample's geometric mean of all features, as propr's defaultivar = "clr". Otherwise features, as names, (1-based) indices, or a logical vector with one value per feature: their geometric mean. One feature gives the additive log ratio (alr, asalr(denominator =)), and that feature is then left out of the result (its alr is 0 in every sample); with several, every feature is kept.- 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.0adds nothing, and is an error whencountshas zeros. See Zeros.- 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 dist object over the features, as vlr() returns, with
method "rho_p".
\(\rho_p\) is a similarity in a dist container: as.matrix()
puts 0 on the diagonal, where \(\rho_p\) is 1, and it must not be
given as dm to an ordination or test. assoc_pairs() lists the
most proportional pairs, such as assoc_pairs(rho, threshold = 0.7),
and as.matrix(rho) > 0.7 gives an adjacency matrix. For a
dissimilarity, use 1 - rho_p(x), which is \(\mathrm{vlr}_{ij} /
(\mathrm{var}(z_i) + \mathrm{var}(z_j))\).
Details
With \(z\) the log-ratio-transformed abundances (clr or alr),
$$\rho_{p,ij} = 1 - \frac{\mathrm{var}(z_i - z_j)}{\mathrm{var}(z_i)
+ \mathrm{var}(z_j)} = \frac{2\,\mathrm{cov}(z_i, z_j)}{\mathrm{var}(z_i)
+ \mathrm{var}(z_j)}$$
where \(\mathrm{var}(z_i - z_j)\) is vlr(). It lies in \([-1,
1]\): 1 for proportional features, 0 for none, -1 for reciprocal ones
(\(z_i = -z_j\)). It is Lin's concordance correlation coefficient of
\(z_i\) and \(z_j\). Unlike vlr(), it depends on the denominator.
A pair of features that are both constant relative to the reference has
no defined \(\rho_p\) (NaN).
Not a correlation of abundances. \(\rho_p\) asks whether two
features keep a constant ratio: it is 1 only for a log ratio with slope 1,
and pairs related by a power law with another exponent, or with unequal
variances, score low. sparcc() starts from the same variance of log
ratios but divides by estimated variances of the log absolute
abundances instead, to estimate their Pearson correlation; that is
possible only under its assumption that most pairs are uncorrelated.
This is the coefficient that propr computes with propr(counts, metric = "rho") (see Zeros for its zero handling). propr also estimates false discovery
rates by permutation (updateCutoffs()), and offers ivar = "iqlr", a
clr over the features of mid-range variance; neither is offered here.
Zeros
Logs of zero are undefined, so zeros need replacing first. With
pseudocount = NULL (the default), no pseudocount is used when
counts has no zeros; otherwise half the smallest non-zero value is
added to every value, with a warning. The recommended input is a table
with its zeros replaced by replace_zeros(), which has none and is
used as it is.
propr (Quinn et al. 2017) replaces only the zeros, by 1, which is not
pseudocount = 1 (that adds 1 to every value). To reproduce it, write
x[x == 0] <- 1 and then call these functions on x.
Pseudocounts are not neutral: in sparse tables the many zeros, all given the same value, can dominate the variances. Filtering out rare features first helps.
Size
The result has \(D(D - 1)/2\) values: 20,000 features give 2e8 pairs, 1.6 GB. Filter out rare features first for large tables. The table itself stays sparse.
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
Erb, I., & Notredame, C. (2016). How should we measure proportionality on relative gene expression data? Theory in Biosciences, 135, 21–36.
Lovell, D., Pawlowsky-Glahn, V., Egozcue, J. J., Marguerat, S., & Bähler, J. (2015). Proportionality: a valid alternative to correlation for relative data. PLoS Computational Biology, 11, e1004075.
Quinn, T. P., Richardson, M. F., Lovell, D., & Crowley, T. M. (2017). propr: an R-package for identifying proportionally abundant features using compositional data analysis. Scientific Reports, 7, 16252.
See also
vlr(), phi_s(), sparcc(), alr(), normalize()
('clr'), replace_zeros().
Examples
x <- replace_zeros(ex_counts, 'mult')
rho <- rho_p(x)
rho
#> # A dist: 6 features (lower triangle)
#> # Proportionality (rho_p)
#> Streptococcus Bacteroides Corynebacterium Haemophilus
#> Bacteroides -0.504
#> Corynebacterium 0.085 -0.646
#> Haemophilus 0.865 -0.215 -0.319
#> Propionibacterium -0.935 0.307 0.203 -0.983
#> Staphylococcus -0.447 -0.412 0.652 -0.536
#> # … 1 more column: Propionibacterium
#> # Attributes: method
# Pairs above a cutoff
assoc_pairs(rho, threshold = 0.5)
#> # A data.frame: 8 × 3
#> # Proportionality (rho_p): pairs with |r| >= 0.5
#> from to association
#> <chr> <chr> <dbl>
#> 1 Haemophilus Propionibacterium -0.983
#> 2 Streptococcus Propionibacterium -0.935
#> 3 Streptococcus Haemophilus 0.865
#> 4 Corynebacterium Staphylococcus 0.652
#> 5 Bacteroides Corynebacterium -0.646
#> 6 Propionibacterium Staphylococcus 0.537
#> 7 Haemophilus Staphylococcus -0.536
#> 8 Streptococcus Bacteroides -0.504
#> # Attributes: method, threshold
# Relative to one feature (alr): that feature is left out
rho_p(x, denominator = 'Streptococcus')
#> # A dist: 5 features (lower triangle)
#> # Proportionality (rho_p)
#> Bacteroides Corynebacterium Haemophilus Propionibacterium
#> Corynebacterium 0.328
#> Haemophilus 0.231 -0.225
#> Propionibacterium 0.762 0.786 0.0277
#> Staphylococcus 0.483 0.903 0.0318 0.887
#> # Attributes: method
