tcgsaseq (version 2.0.5)

varcompseq: Variance component testing for RNA-seq data analysis

Description

Wrapper function for gene-by-gene association testing of RNA-seq data

Usage

varcompseq(
  exprmat,
  covariates,
  variables2test,
  sample_group = NULL,
  weights_var2test_condi = TRUE,
  cov_variables2test_eff = diag(ncol(variables2test)),
  which_test = c("permutation", "asymptotic"),
  which_weights = c("loclin", "voom", "none"),
  n_perm = 1000,
  progressbar = TRUE,
  parallel_comp = TRUE,
  nb_cores = parallel::detectCores() - 1,
  preprocessed = FALSE,
  doPlot = TRUE,
  gene_based_weights = FALSE,
  bw = "nrd",
  kernel = c("gaussian", "epanechnikov", "rectangular", "triangular", "biweight",
    "tricube", "cosine", "optcosine"),
  exact = FALSE,
  transform = TRUE,
  padjust_methods = c("BH", "BY", "holm", "hochberg", "hommel", "bonferroni"),
  lowess_span = 0.5,
  na.rm_varcompseq = TRUE,
  homogen_traj = FALSE
)

Arguments

exprmat

a numeric matrix of size G x n containing the raw RNA-seq counts or preprocessed expressions from n samples for G genes.

covariates

a numeric matrix of size n x p containing the model covariates from n samples (design matrix). Usually, its first column is the intercept (full of 1s).

variables2test

a numeric design matrix of size n x K containing the K variables to be tested

sample_group

a vector of length n indicating whether the samples should be grouped (e.g. paired samples or longitudinal data). Coerced to be a factor. Default is NULL in which case no grouping is performed.

weights_var2test_condi

a logical flag indicating whether heteroscedasticity weights computation should be conditional on both the variables to be tested variables2test and on the covariates, or on covariates alone. Default is TRUE in which case conditional means are estimated conditionally on both variables2test and covariates.

cov_variables2test_eff

a matrix of size K x K containing the covariance matrix of the K random effects. Only used if homogen_traj is FALSE. Default assume diagonal correlation matrix, i.e. independence of random effects.

which_test

a character string indicating which method to use to approximate the variance component score test, either "permutation" or "asymptotic". Default is "permutation".

which_weights

a character string indicating which method to use to estimate the mean-variance relationship weights. Possibilities are "loclin", "voom" or "none" (in which case no weighting is performed). Default is "loclin". See sp_weights and voom_weights for details.

n_perm

the number of perturbations. Default is 1000.

progressbar

logical indicating whether a progress bar should be displayed when computing permutations (only in interactive mode).

parallel_comp

a logical flag indicating whether parallel computation should be enabled. Only Linux and MacOS are supported, this is ignored on Windows. Default is TRUE.

nb_cores

an integer indicating the number of cores to be used when parallel_comp is TRUE. Only Linux and MacOS are supported, this is ignored on Windows. Default is parallel::detectCores() - 1.

preprocessed

a logical flag indicating whether the expression data have already been preprocessed (e.g. log2 transformed). Default is FALSE, in which case y is assumed to contain raw counts and is normalized into log(counts) per million.

doPlot

a logical flag indicating whether the mean-variance plot should be drawn. Default is FALSE.

gene_based_weights

a logical flag used for "loclin" weights, indicating whether to estimate weights at the gene-level, or rather at the observation-level. Default is FALSE, which is what it should be for gene-wise analysis.

bw

a character string indicating the smoothing bandwidth selection method to use. See bandwidth for details. Possible values are "ucv", "SJ", "bcv", "nrd" or "nrd0"

kernel

a character string indicating which kernel should be used. Possibilities are "gaussian", "epanechnikov", "rectangular", "triangular", "biweight", "tricube", "cosine", "optcosine". Default is "gaussian" (NB: "tricube" kernel corresponds to the loess method).

exact

a logical flag indicating whether the non-parametric weights accounting for the mean-variance relationship should be computed exactly or extrapolated from the interpolation of local regression of the mean against the variance. Default is FALSE, which uses interpolation (faster computation).

transform

a logical flag used for "loclin" weights, indicating whether values should be transformed to uniform for the purpose of local linear smoothing. This may be helpful if tail observations are sparse and the specified bandwidth gives suboptimal performance there. Default is TRUE.

padjust_methods

multiple testing correction method used if genesets is a list. Default is "BH", i.e. Benjamini-Hochberg procedure for controlling the FDR. Other possibilities are: "holm", "hochberg", "hommel", "bonferroni" or "BY" (for Benjamini-Yekutieli procedure).

lowess_span

smoother span for the lowess function, between 0 and 1. This gives the proportion of points in the plot which influence the smooth at each value. Larger values give more smoothness. Only used if which_weights is "voom". Default is 0.5.

na.rm_varcompseq

logical: should missing values in y (including NA and NaN) be omitted from the calculations? Default is FALSE.

homogen_traj

a logical flag indicating whether trajectories should be considered homogeneous. Default is FALSE in which case trajectories are not only tested for trend, but also for heterogeneity.

Value

A list with the following elements:

• which_test: a character string carrying forward the value of the 'which_test' argument indicating which test was perform (either "asymptotic" or "permutation").

• preprocessed: a logical flag carrying forward the value of the 'preprocessed' argument indicating whether the expression data were already preprocessed, or were provided as raw counts and transformed into log-counts per million.

• n_perm: an integer carrying forward the value of the 'n_perm' argument indicating the number of perturbations performed (NA if asymptotic test was performed).

• genesets: carrying forward the value of the 'genesets' argument defining the gene sets of interest (NULL for gene-wise testing).

• pval: computed p-values. A data.frame with one raw for each each gene set, or for each gene if genesets argument is NULL, and with 2 columns: the first one 'rawPval' contains the raw p-values, the second one contains the FDR adjusted p-values (according to the 'padjust_methods' argument) and is named 'adjPval'.

References

Agniel D & Hejblum BP (2017). Variance component score test for time-course gene set analysis of longitudinal RNA-seq data, Biostatistics, 18(4):589-604. 10.1093/biostatistics/kxx005. arXiv:1605.02351.

See Also

sp_weights vc_test_perm vc_test_asym p.adjust

Examples

# NOT RUN {
#rm(list=ls())
nsims <- 2 #100
res <- numeric(nsims)
for(i in 1:nsims){
n <- 1000
nr=5
ni=50
r <- nr*ni
t <- matrix(rep(1:nr), ni, ncol=1, nrow=r)
sigma <- 0.5
b0 <- 1

#under the null:
b1 <- 0

y.tilde <- b0 + b1*t + rnorm(r, sd = sigma)
y <- t(matrix(rnorm(n*r, sd = sqrt(sigma*abs(y.tilde))), ncol=n, nrow=r) +
      matrix(rep(y.tilde, n), ncol=n, nrow=r))
x <- matrix(1, ncol=1, nrow=r)

#run test
res_genes <- varcompseq(exprmat=y, covariates=x, variables2test=t, sample_group=rep(1:ni, each=nr),
                   which_test="asymptotic",
                   which_weights="none", preprocessed=TRUE)
mean(res_genes$pvals[, "rawPval"]>0.05)
quantile(res_genes$pvals[, "rawPval"])
res[i] <- mean(res_genes$pvals[, "rawPval"]<0.05)
cat(i,"\n")
}
mean(res)

# }
# NOT RUN {
b0 <- 1
b1 <- 0
y.tilde <- b0 + b1*t + rnorm(r, sd = sigma)
y <- t(matrix(rnorm(n*r, sd = sqrt(sigma*abs(y.tilde))), ncol=n, nrow=r) +
      matrix(rep(y.tilde, n), ncol=n, nrow=r))
res_genes <- varcompseq(exprmat=y, covariates=x, variables2test=t, sample_group=rep(1:ni, each=nr),
                   which_weights="none", preprocessed=TRUE)
summary(res_genes$pvals)
# }