MetaDeconfound {metadeconfoundR}

MetaDeconfound

Description

MetaDeconfound checks all feature <-> covariate combinations for counfounding effects of covariates on feature <-> effect correlation

Usage

MetaDeconfound(
  featureMat,
  metaMat,
  nnodes = 1,
  adjustMethod = "fdr",
  robustCutoff = 5,
  QCutoff = 0.1,
  DCutoff = 0,
  PHS_cutoff = 0.05,
  logfile = NULL,
  logLevel = "INFO",
  startStop = NA,
  QValues = NA,
  DValues = NA,
  minQValues = NULL,
  deconfT = NULL,
  deconfF = NULL,
  doConfs = 0,
  doRanks = NA,
  randomVar = NA,
  fixedVar = NA,
  robustCutoffRho = NULL,
  typeCategorical = NULL,
  typeContinuous = NULL,
  logistic = FALSE,
  rawCounts = FALSE,
  returnLong = FALSE,
  collectMods = FALSE,
  ...
)

Arguments

featureMat

a data frame with row(sample ID) and column(feature such as metabolite or microbial OTU ) names, listing features for all samples

metaMat

a data frame with row(sample ID) and column(meta data such as age,BMI and all possible confounders) names listing metadata for all samples. first column should be case status with case=1 and control=0. All binary variables need to be in 0/1 syntax!

nnodes

number of nodes/cores to be used for parallel processing

adjustMethod

multiple testing p-value correction using one of the methods of p.adjust.methods

robustCutoff

minimal number of sample size for each covariate in order to have sufficient power for association testing

QCutoff

significance cutoff for q-value, DEFAULT = 0.1

DCutoff

effect size cutoff (either cliff's delta or spearman correlation test estimate), DEFAULT = 0

PHS_cutoff

PostHoc Significance cutoff

logfile

name of optional logging file.

logLevel

logging verbosity, possible levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, DEFAULT = INFO

startStop

vector of optional strings controlling which parts of the pipeline should be executed. ("naiveStop": only naive associations will be computed, no confounder analysis is done)

QValues

optional data.frame containing pre-computed multiple-testing corrected p-values for naive associations

DValues

optional data.frame containing pre-computed effect sizes for naive associations

minQValues

pessimistic qvalues, can be generated by ImportLongPrior. This dataframe of QValues is used to incorporate prior knowledge of potential associations between individual features and metadata by supplying QValues < QCutoff for these associations. All significant associations thus reported will be treated as potentially confounding influences.

deconfT

vector of metavariable names *always* to be included as potential confounder

deconfF

vector of metavariable names *never* to be included as potential confounder

doConfs

optional parameter for additional computation of confidence interval of linear models in the deconfounding step (0 = no , 1 = logging, 2 = strict)

doRanks

optional vector of metavariable names, that should be rank transformed when building linear models in the doconfounding step

randomVar

optional vector of metavariable names to be treated as random effect variables. These variables will not be tested for naive associations and will not be included as potential confounders, but will be added as random effects "+ (1|variable)" into any models being built. Any associations reducible to the supplied random effect(s) will be labeled as "NS". Note: Ps, Qs, Ds are computed independently and thereby not changed through inclusion of random effects.

fixedVar

optional vector of metavariable names to be treated as fixed effect variables. These variabels will not be tested for naive associations and will not be included as potential confounders, but will be added as fixed effects "+ variable" into any models being built. Any associations reducible to the supplied fixed effect(s) will be labeled as "NS". Note: Ps, Qs, Ds are computed independently and thereby not changed through inclusion of fixed effects.

robustCutoffRho

optional robustness cutoff for continuous variables

typeCategorical

optional character vector of metavariable names to always be treated as categorical

typeContinuous

optional character vector of metavariable names to always be treated as continuous

logistic

optional logical parameter; DEFAULT = FALSE; Set TRUE to treat supplied features as binary instead of continuous

rawCounts

optional logical parameter; DEFAULT = FALSE; Set TRUE to treat supplied features as not normalized/rarefied counts; metadeconfoundR will compute total read count per sample and include this information in the modelling steps. WARNING: naive associations computed in first part of metadeconfoundR are reliant on normalized/rarefied data. Please split your analysis up into 2 parts as shown in the documentation when using this mode..

returnLong

DEFAULT = FALSE; Set TRUE to get output in one long format data.frame instead of list of four wide format data.frames

collectMods

DEFAULT = FALSE; Set TRUE to collect all model objects generated by Metadeconfound and return them in a nested list alongside the standard Ps/Qs/Ds/status output.

...

for additional arguments used internally (development/debugging)

Details

for more details and explanations please see the vignette.

Value

list with elements (or data.frame with columns, when returnLong = TRUE) Ds = effectsize, Ps = uncorrected p-value for naive association, Qs = multiple testing corrected p-value/fdr, and status = confounding status for all feature <=> covariate combinations with following categories: (NS = not significant, OK_sd = strictly deconfounded, OK_nc = no covariates, OK_d = doubtful, AD = ambiguously deconfounded, C: followed by comma separated covariate names = confounded by listed covariates)

Can be plotted using BuildHeatmap.

Examples

data(reduced_feature)
data(metaMatMetformin)

example_output <- MetaDeconfound(featureMat = reduced_feature,
                                  metaMat = metaMatMetformin,
                                  logLevel = "ERROR")