test.contrast_adjust: Test a contrast and perform FDR correction

In statOmics/MSqRob: Robust statistical inference for quantitative LC-MS proteomics

Test a contrast and perform FDR correction

Description

A shortcut version for contrast testing and multiple testing correction using the test.protLMcontrast, prot.p.adjust and prot.signif functions sequentially.

Usage

test.contrast_adjust(protLM, L, level = 0.05, method = "fdr",
  pcol = "pval", qname = "qval", Tcol = NULL, threshold_excess1 = 1e-90,
  add.annotations = TRUE, simplify = TRUE, lfc = 0, anova = FALSE,
  anova.na.ignore = TRUE, type_dfs = "residual", custom_dfs = NULL,
  exp_unit = NULL, pars_between = NULL, lmerModFun = NULL,
  gradMethod = "simple", printProgress = FALSE, shiny = FALSE,
  message_extract = NULL, message_test = NULL)

Arguments

protLM	An object of class protLM.
L	A contrast matrix with the parameter levels as rows and a column for each contrast.
level	The significance level at which the q-value needs to be controlled. Defaults to 5%.
method	Correction method. Can be abbreviated. Defaults to "fdr". To get all available methods, type c("fdrtool", p.adjust.methods). For more information on the "fdrtool" method, check out the package fdrtool by Bernd Klaus and Korbinian Strimmer. For more information on the other methods, see the p.adjust function.
pcol	A character string or numeric index indicating the column containing the p-values. Defaults to "pval".
qname	A character string indicating the name that will be given to the column containing the q-values. Defaults to "qval".
Tcol	Only needed when method = "fdrtool". A character string or numeric index indicating the column containing the T-values. Defaults to NULL.
threshold_excess1	A numeric value between 0 and 1 indicating the threshold at which correcting for an excess in p-values close to 1 should be performed. This is sometimes needed when a null distribution needs to be fitted. Note that the method still accounts for the total number of p-values when performing this correction. Only if there is, according to a binomial test, a significant enrichment of p-values above an automatically determined cut-off at the threshold_excess1 significance level, a correction for enrichment in p-values close to 1 will be performed. If you never want to correct for an excess in p-values close to 1, set threshold_excess1 to 0. If you always want to correct for an excess in p-values close to 1, set threshold_excess1 to 1. Defaults to 1e-90.
add.annotations	A logical indicating whether the annotations slot of the protLM object should be added as extra columns to each matrix in the returned list of matrices. Defaults to TRUE.
simplify	A logical indicating wheter, if there is only one contrast, a matrix should be returned instead of a list containing one matrix. Defaults to TRUE.
lfc	The minimum (log2) fold-change that is considered scientifically meaningful. Defaults to 0. Ignored when anova = TRUE.
anova	A logical indicating whether the contrasts should be tested simultaneously in one F-test (anova = TRUE) or as separate t-tests (anova = FALSE). Defaults to FALSE.
anova.na.ignore	A logical indicating whether contrasts that cannot be fitted due to missing observations should be ignored when calculating an F value (anova.na.ignore = TRUE) or NA should be returned when at least one contrast cannot be estimated (anova.na.ignore = FALSE). Defaults to TRUE. Ignored when anova = FALSE.
type_dfs	Either one of "residual", "between-within", "Satterthwaite", "exp_between" or "custom". This argument indicates how the degrees of freedom should be calculated. Defaults to "residual". More information is given under 'Details'.
custom_dfs	Only used if type_dfs="custom". A list of length equal to the number of models in protLM containing vectors of lenght ncol(L) (if anova = FALSE) representing the degrees of freedom that should be used for each contrast in L and each model in the protLM object. If anova = TRUE, each element of the list should contain a single numeric value representing the degrees of freedom to be used for the anova test. Defaults to NULL.
exp_unit	Only used if type_dfs="exp_between". The effect that in all models corresponds to the experimental unit.
pars_between	Only used if type_dfs="exp_between". Character vector indicating all parameters in the models that are between-treatment effects. If left to default (NULL), all parameters in the models will be asumed to be between-treatment effects (this is not adviced as the result will mostly be too conservative).
lmerModFun	Only used when satterthwaite=TRUE. lmerModFun indicates which deviance function should be used when calculating the Satterthwaite approximation for the degrees of freedom. The default (NULL) uses the lme4 mkLmerDevfun function to generate the deviance function. This parameter should only rarely, if ever, be changed.
gradMethod	Only used when satterthwaite=TRUE. One of "Richardson", "simple", or "complex" indicating the method to use for the gradient calculation by numerical approximation during the calculation of the Satterthwaite approximation for the degrees of freedom. Defaults to "simple".
printProgress	A logical indicating whether the R should print a message before calculating the contrasts for each accession. Defaults to FALSE.
shiny	A logical indicating whether this function is being used by a Shiny app. Setting this to TRUE only works when using this function in a Shiny app and allows for dynamic progress bars. Defaults to FALSE.
message_extract	Only used when printProgress=TRUE and shiny=TRUE. A single-element character vector: the message to be displayed to the user during the extraction of beta, vcov, df and sigma, or NULL to hide the current message (if any).
message_test	Only used when printProgress=TRUE and shiny=TRUE. A single-element character vector: the message to be displayed to the user during the testing of the contrasts, or NULL to hide the current message (if any).

Details

Calculating degrees of freedom (and hence p values) for mixed models with unbalanced designs is an unresolved issue in the field (see for example here https://stat.ethz.ch/pipermail/r-help/2006-May/094765.html and here https://stat.ethz.ch/pipermail/r-sig-mixed-models/2008q2/000904.html). We offer different approximations and leave it up to the user to select his/her preferred approach. "residual" calculates approximative degrees of freedom by subtracting the trace of the hat matrix from the number of observations. It is the default setting, but this approach might be somewhat too liberal. "Satterthwaite" calculates approximative degrees of freedom using Satterthwaite's approximation (Satterthwaite, 1946). This approximative approach is used in many applications but is rather slow to calculate and might lead to some missing values due difficulties in calculating the Hessian. "exp_between" calculates approximative degrees of freedom by defining on which level the treatments were executed and substracting all degrees of freedom lost due to between-treatement effects (pars_between) from the number of experimental units exp_unit. This allows to mimick the behaviour of type_dfs="between-within" for more complex designs. "custom" Allows the user to provide his/her own degrees of freedom for each contrast and each protein. Custom degrees of freedom should be entered in the custom_dfs field.

Value

A list of matrices, with each matrix in the list corresponding to a contrast in L. Each row of the matrix corresponds to an accession in the protLM object. The estimate column contains the size estimate of the contrast, the se column contains the estimated standard error on the contrast, the Tval column contains the T-value corresponding to the contrast, the pval column holds the p-value corresponding to the contrast and the qval column holds the corrected p-values. Each matrix is sorted from smalles to largest pval with NA values at the bottom of the matrices. If simplify=TRUE and the protLM object contains only one element, the matrix is not present in a list.

References

F. E. Satterthwaite. An Approximate Distribution of Estimates of Variance Components. Biometrics Bulletin, 1946.

Strimmer, K. (2008a). A unified approach to false discovery rate estimation. BMC Bioinformatics 9: 303. Available from http://www.biomedcentral.com/1471-2105/9/303/.

Strimmer, K. (2008b). fdrtool: a versatile R package for estimating local and tail area- based false discovery rates. Bioinformatics 24: 1461-1462. Available from http://bioinformatics.oxfordjournals.org/cgi/content/abstract/24/12/1461.

statOmics/MSqRob documentation built on Dec. 8, 2022, 6 a.m.