propd: The propd Method

In tpq/propr: An R package to calculate proportionality and other measures for compositional data

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 N1 and N2. 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 \alpha, 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 signature 'propd'
show(object)

propd(
  counts,
  group,
  alpha = NA,
  p = 0,
  weighted = FALSE,
  weights = as.matrix(NA)
)

setDisjointed(propd)

setEmergent(propd)

setActive(propd, what = "theta_d")

updateF(propd, moderated = FALSE, ivar = "clr")

Arguments

object	A propd object.
counts	A data matrix representing counts. It is assumed that the matrix contains numerical values only.
group	A character vector representing group labels indicating the assignment of each count to different groups.
alpha	The alpha parameter used in the alpha log-ratio transformation.
p	The number of permutations to perform for calculating the false discovery rate (FDR). The default is 0.
weighted	A logical value indicating whether weighted calculations should be performed.
weights	A matrix of weights. This parameter is optional and used only if 'weighted = TRUE'. If not provided, the function will use limma- based weights for the calculations.
propd	A propd object.
what	A character string. The theta type to set active.
moderated	For updateF, a boolean. Toggles whether to calculate a moderated F-statistic.
ivar	See propr method.

Details

The propd function creates a propd object, which is used for differential analysis of regulatory relationships between features. It performs log-ratio transformation, calculates the variance of log-ratio (VLR), and computes the theta values using different formulas. The object stores the count matrix, group labels, alpha parameter, and other relevant information needed for further analysis and visualization.

Value

A propd object containing the computed theta values, associated count matrix, group labels, and other calculated statistics.

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

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

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

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.

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.

Examples

# Sample input count data and group assignments
data <- iris[1:100, 1:4]
group <- iris[1:100, 5]

# Create a propd object for differential analysis
result <- propd(data, group, alpha = 0.5)

tpq/propr documentation built on Feb. 3, 2025, 4:23 a.m.