propr: The propr Package

Description

Welcome to the propr package!

To learn more about calculating proportionality, see Details.

To learn more about visualizing proportionality, see visualize.

To learn more about ALDEx2 package integration, see aldex2propr.

To learn more about differential proportionality, see propd.

To learn more about compositional data analysis, and its relevance to biological count data, see the bundled vignette.

Usage

# S4 method for propr
show(object)
propr(counts, metric = c("rho", "phi", "phs", "cor", "vlr"),
  ivar = "clr", select, symmetrize = FALSE, alpha, p = 100)
phit(counts, ...)
perb(counts, ...)
phis(counts, ...)
corr(counts, ...)
# S4 method for propr
subset(x, subset, select)
# S4 method for propr
[(x, i = "all", j, tiny = FALSE)
simplify(object)
updateCutoffs.propr(object, cutoff, ncores)

Arguments

object

A propr or propd object.

counts

A data.frame or matrix. A "count matrix" with subjects as rows and features as columns. Note that this matrix does not necessarily have to contain counts.

metric

A character string. The proportionality metric to calculate. Choose from "rho", "phi", or "phs".

ivar

A numeric scalar. Specifies reference feature(s) for additive log-ratio transformation. The argument will also accept feature name(s) instead of the index position(s). Set to "iqlr" to use inter-quartile log-ratio transformation. Ignore to use centered log-ratio transformation.

select

Optional. Use this to subset the final proportionality matrix without altering the result. Use this argument to rearrange feature order.

symmetrize

A logical. If TRUE, forces symmetry by reflecting the "lower left triangle".

alpha

A double. See vignette for details. Leave missing to skip Box-Cox transformation.

An integer. The number of permutation cycles.

...

Arguments passed to the wrapped method.

A propr or propd object.

subset

Subsets via object@counts[subset, ]. Use this argument to rearrange subject order. For backwards compatibility.

Operation used for the subset indexing. Select from "==", "=", ">", ">=", "<", "<=", "!=", or "all". For backwards compatibility.

Provide a numeric value to which to compare the proportionality measures in the @matrix slot. For backwards compatibility.

tiny

A logical scalar. Toggles whether to pass the indexed result through simplify. For backwards compatibility.

cutoff

For updateCutoffs, a numeric vector. this argument provides the FDR cutoffs to test. For graph functions, a numeric scalar. This argument indicates the maximum theta to include in the figure. For graph functions, a large integer will instead retrieve the top N pairs as ranked by theta.

ncores

An integer. The number of parallel cores to use.

Value

Returns a propr object.

Slots

counts: A data.frame. Stores the original "count matrix" input.

alpha

A double. Stores the alpha value used for transformation.

metric

A character string. The metric used to calculate proportionality.

ivar

A vector. The reference used to calculate proportionality.

logratio

A data.frame. Stores the transformed "count matrix".

matrix

A matrix. Stores the proportionality matrix.

pairs

A vector. Indexes the proportional pairs of interest.

results

A data.frame. Stores the pairwise propr measurements.

permutes

A list. Stores the shuffled transformed "count matrix" instances, used to reproduce permutations of propr.

fdr

A data.frame. Stores the FDR cutoffs for propr.

Methods (by generic)

show: Method to show propr object.

subset: Method to subset propr object.

[: Method to subset propr object.

Functions

phit: A wrapper for propr(counts, metric = "phi", ...).

perb: A wrapper for propr(counts, metric = "rho", ...).

phis: A wrapper for propr(counts, metric = "phs", ...).

corr: A wrapper for propr(counts, metric = "cor", ...).

simplify: This convenience function takes an indexed propr object and subsets the object based on that index. Then, it populates the @pairs slot of the new object with an updated version of the original index. You can call simplify from within the [ method using the argument tiny.

updateCutoffs: Use the propr object to permute proportionality across a number of cutoffs. Since the permutations get saved when the object is created, calling updateCutoffs will use the same random seed each time.

Details

Let D represent a number of features measured across N samples. This function calculates proportionality from a data set with N rows and D columns. One can think of phi as analogous to a distance matrix, except that it has no symmetry unless forced. One can think of rho as analogous to a correlation matrix. One can think of phs as either a naturally symmetric variant of phi or a monotonic variant of rho. Also, one can use corr to calculate correlation from log-ratio transformed data.

This function depends on a reference and uses the centered log-ratio transformation by default. The user may also specify any number of features (by index or name) to use as a reference instead. Alternatively, ivar = "iqlr" will transform data using the geometric mean of features with variances that fall in the inter-quartile range of all per-feature variances (based on the ALDEx2 package).

The propr method calculates proportionality. This fails in the setting of zero counts. The propr method will use a Box-Cox transformation to approximate VLR based on the parameter \(\alpha\), if provided. We refer the user to the vignette for more details.