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. However, VLR 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.
# S4 method for propd
show(object)propd(counts, group, alpha, p = 100, weighted = FALSE)
propd2propr(object, ivar)
setActive(propd, what = "theta_d")
setDisjointed(propd)
setEmergent(propd)
# S4 method for propd,missing
plot(x, y, cutoff = 1000, col1, col2, propr,
prompt = TRUE, d3 = FALSE, plotSkip = FALSE)
shale(object, cutoff = 1000, k, prompt = TRUE, clean = FALSE)
geyser(object, cutoff = 1000, k = 5, prompt = TRUE, plotly = FALSE)
bowtie(object, cutoff = 1000, k = 5, prompt = TRUE, plotly = FALSE)
gemini(object, cutoff = 1000, k = 5, prompt = TRUE, plotly = FALSE)
slice(object, cutoff = 1000, reference, prompt = TRUE, plotly = FALSE)
decomposed(object, cutoff = 1000, prompt = TRUE)
updateCutoffs(propd, cutoff = seq(0.05, 0.95, 0.3))
updateF(propd, moderated = FALSE, ivar = "clr")
A propd object.
A data.frame or matrix. A "count matrix" with subjects as rows and features as columns.
A character vector. Group or sub-group memberships,
ordered according to the row names in counts.
A double. See vignette for details. Leave missing to skip Box-Cox transformation.
An integer. The number of permutation cycles.
A boolean. Toggles whether to calculate
theta using limma::voom weights.
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.
A character string. The theta type to set active.
Missing. Ignore. Leftover from the generic method definition.
For updateCutoffs, a numeric vector.
this argument provides the FDR cutoffs to test for theta.
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.
A character vector. Specifies which nodes
to color red or blue, respectively.
A character vector. Specifies which nodes
to color red or blue, respectively.
An indexed propr object. Use to add
proportional edges (colored green) to a propd network.
A logical scalar. Set to FALSE to disable
the courtesy prompt when working with big data.
A boolean. Use rgl to plot 3D network.
A boolean. Toggles whether to build
the network graph without plotting it.
Used by pals.
An integer. The maximum number of PALs to index
when calculating pals in the network.
A boolean. Toggles whether to remove pairs
with "Bridged" or "Missing" PALs. Used by geyser,
bowtie, and gemini.
A logical scalar. Set to TRUE to produce
a dynamic plot using the plotly package.
A character string. A feature to use as the denominator reference when comparing log-ratio abundances.
For updateF, a boolean. Toggles
whether to calculate a moderated F-statistic.
countsA data.frame. Stores the original "count matrix" input.
groupA character vector. Stores the original group labels.
alphaA double. Stores the alpha value used for transformation.
weightedA logical. Stores whether the theta is weighted.
weightsA matrix. If weighted, stores the limma-based weights.
activeA character. Stores the name of the active theta type.
thetaA data.frame. Stores the pairwise theta measurements.
FivarANY. Stores the reference used to moderate theta.
dfzA double. Stores the prior df used to moderate theta.
permutesA data.frame. Stores the shuffled group labels, used to reproduce permutations of theta.
fdrA data.frame. Stores the FDR cutoffs for theta.
show: Method to show propd object.
plot: Method to plot propd object.
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. These provide the same results as
setDisjointed and setEmergent, respectively.
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.
plot:
Plots the interactions between pairs as a network.
When plotting disjointed proportionality, red edges
indicate that LRM1 > LRM2 while blue edges indicate
that LRM1 < LRM2. When plotting emergent proportionality,
red edges indicate that VLR1 < VLR2 while blue edges
indicate that VLR1 > VLR2. Group labels numbered based on
the order of the group argument to propd.
Use col1 and col2 arguments to color nodes.
For more control over the visualization of the network,
consider exporting the table from shale to a
network visualization tool like Cytoscape.
shale:
Builds a table of within-group and total log-ratio
variances, log-ratio means, and PALs (see: pals).
If the argument k is provided, the table will
label at most k top PALs. Just as each node
gets assigned a PAL, shale aims to assign
each edge a PAL. Edges that have a top PAL as one
and only one of their nodes get assigned that PAL.
Edges that have top PALs as both of their nodes
get assigned "Bridged". Edges without a top PAL
as one of their nodes will get assigned a PAL if
either (a) both nodes have the same neighbor PAL
or (b) one node has a "Missing" neighbor PAL.
The cutoff argument guides the maximum value of
theta above which to exclude the pair. A large integer
cutoff will instead retrieve the top N pairs as
ranked by theta.
geyser:
Plots indexed pairs based on the within-group
log-ratio variance (VLR) for each group. Pairs near the
origin show a highly proportional relationship in
both groups. Each line away from the y = x line
indicates a doubling of VLR compared to the other group.
All pairs colored based on PAL
(see: pals).
See gemini.
bowtie:
Plots indexed pairs based on the log-ratio means
(LRM), relative to its PAL, for each group. Pairs near
the origin show comparable LRM, relative to its PAL, in
both groups. Each line away from the y = x line
indicates a doubling of LRM compared to the other group.
All pairs colored based on PAL
(see: pals).
See gemini.
gemini:
Plots indexed pairs based on the log-fold difference
in log-ratio variance (VLR) between the two groups
versus the difference in log-ratio means (LRM). In this
figure, the LRM for each group is signed (i.e., positive
or negative) such that the PAL is the denominator
of the log-ratio. This allows for a fluid comparison
between pairs within the same PAL module. Pairs with a
"Bridged" or "Missing" PAL get excluded from this graph.
Remember that an increase in VLR suggests less
proportionality. All pairs colored based on PAL
(see: pals).
slice:
Plots log-ratio counts relative to a reference
node for all pairs that include the reference itself.
This makes a useful adjunct function to visualize how
features vary across samples relative to a PAL.
decomposed:
Plots the decomposition of log-ratio variance into
(weighted) group variances and between-group variance.
Useful for visualizing how a theta type selects pairs.
propd2propr:
Transforms a propd object into a propr object
where the @matrix slot contains \(1 - \theta\).
Allows the user to interrogate theta using any
function described in visualize.