mbecBox: Feature Differential Abundance Box-Plot

In buschlab/MBECS: Evaluation and correction of batch effects in microbiome data-sets

Description

Displays the abundance of a selected feature, grouped/colored by a covariate, i.e., batch, in a box-plot. Includes the density-plot, i.e., the distribution of counts for each sub-group. Selection methods for features are "TOP" and "ALL" which select the top-n or all features respectively. The default value for the argument 'n' is 10. If 'n' is supplied with a vector of feature names, e.g., c("OTU1","OTU5", "OTU10"), of arbitrary length, the argument 'method' will be ignored and only the given features selected for plotting.

Usage

mbecBox(
  input.obj,
  method = c("ALL", "TOP"),
  n = 10,
  model.var = "batch",
  type = "clr",
  label = character(),
  return.data = FALSE
)

Arguments

input.obj	MbecData object
method	One of 'ALL' or 'TOP' for 'n' most variable features, DEFAULT is 'ALL'.
n	Number of OTUs to display for 'TOP' method, or vector of specific feature names to select.
model.var	Covariate to group by, default is "batch".
type	Which abundance matrix to use for the calculation.
label	Which corrected abundance matrix to use for analysis.
return.data	logical if TRUE returns the data.frame required for plotting. Default (FALSE) will return plot object.

Details

The function returns either a plot-frame or the finished ggplot object. Input is an MbecData-object. If cumulative log-ratio (clr) and total sum-scaled (tss) abundance matrices are part of the input, i.e., 'mbecTransform()' was used, they can be selected as input by using the 'type' argument with either "otu", "clr" or "tss". If batch effect corrected matrices are available, they can be used by specifying the 'type' argument as "cor" and using the 'label' argument to select the appropriate matrix by its denominator, e.g., for batch correction method ComBat this would be "bat", for RemoveBatchEffects from the limma package this is "rbe". Default correction method-labels are "ruv3", "bmc","bat","rbe","pn","svd".

The combination of 'type' and 'label' argument basically accesses the attribute 'cor', a list that stores all matrices of corrected counts. This list can also be accessed via getter and setter methods. Hence, the user can supply their own matrices with own names.

Value

either a ggplot2 object or a formatted data-frame to plot from

Examples

# This will return the plot-frame of all features in the data-set.
data.Box <- mbecBox(input.obj=dummy.mbec, method='ALL', model.var='batch',
type='clr', return.data=TRUE)

# This will return the ggplot2 object of the top 5 most variable features.
plot.Box <- mbecBox(input.obj=dummy.mbec, method='TOP', n=5,
model.var='batch', type='otu', return.data=FALSE)

buschlab/MBECS documentation built on Jan. 21, 2022, 1:27 a.m.