propd: The propd Method

Description

Welcome to the propd method!

Let $X$ and $Y$ be non-zero positive feature vectors measured across $N$ samples belonging to one of two groups, sized $N 1$ and $N 2$ . We use VLR to denote the variance of the log of the ratio of the vectors $X$ over $Y$ . We define theta as the weighted sum of the within-group VLR divided by the weighted total VLR.

The propd method calculates theta. This fails in the setting of zero counts. The propd method will use a Box-Cox transformation to approximate VLR based on the parameter $α$ , if provided. We refer the user to the vignette for more details.

Note that Group 1 always refers to the first element of the group vector argument supplied to propd.

Usage

# S4 method for propd
show(object)
propd(counts, group, alpha, p = 100, weighted = FALSE)
setActive(propd, what = "theta_d")
setDisjointed(propd)
setEmergent(propd)
updateCutoffs.propd(object, cutoff = seq(0.05, 0.95, 0.3))
updateF(propd, moderated = FALSE, ivar = "clr")

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.

group

A character vector. Group or sub-group memberships, ordered according to the row names in counts.

alpha

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

An integer. The number of permutation cycles.

weighted

A boolean. Toggles whether to calculate theta using limma::voom weights.

propd

A propr or propd object.

what

A character string. The theta type to set active.

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.

moderated

For updateF, a boolean. Toggles whether to calculate a moderated F-statistic.

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.

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.

group

A character vector. Stores the original group labels.

weighted

A logical. Stores whether the theta is weighted.

weights

A matrix. If weighted, stores the limma-based weights.

active

A character. Stores the name of the active theta type.

Fivar

ANY. Stores the reference used to moderate theta.

dfz

A double. Stores the prior df used to moderate theta.

results

A data.frame. Stores the pairwise propd measurements.

permutes

A data.frame. Stores the shuffled group labels, used to reproduce permutations of propd.

fdr

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

Methods (by generic)

show: Method to show propd object.

Functions

setActive: Build analyses and figures using a specific theta type. For example, set what = "theta_d" to analyze disjointed proportionality and what = "theta_e" to analyze emergent proportionality.

setDisjointed: A wrapper for setActive(propd, what = "theta_d").

setEmergent: A wrapper for setActive(propd, what = "theta_e").

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

updateF: Use the propd object to calculate the F-statistic from theta as described in the Erb et al. 2017 manuscript on differential proportionality. Optionally calculates a moderated F-statistic using the limma-voom method. Supports weighted and alpha transformed theta values.