ARTP2 (version 0.9.45)

warm.start: Performing ARTP2 test with warm start

Description

This function is designed to accelerate the ARTP2 test in practice. It uses pre-calculated and reusable statistics as input and allow the users to try different testing configuration more efficiently. See Details for more information.

Usage

warm.start(setup, nperm = NULL, lambda = 1.0, nthread = NULL)

Arguments

setup

an R object created by sARTP or rARTP. It is a list containing necessary statistics for computing p-values.

nperm

the number of permutations. If it is NULL as default, then the value in the saved setup will be used. See Details.

lambda

inflation factor to be adjusted in pathway analysis. lambda in this function can only be a single numeric number, which is different from the one in sARTP. The default is 1.0.

nthread

number of threads to be used in permutation. NULL if setup$options$nthread is used.

Value

warm.start returns an object of class ARTP2. It is a list containing the following components:

pathway.pvalue

final pathway p-value accounting for multiple comparisons.

gene.pvalue

a data frame containing gene name, number of SNPs in the gene that were included in the analysis, chromosome name, and the p-value for the gene accounting for multiple comparisons.

pathway

a data frame defining the pathway that was actually tested after various filters applied.

model

a list containing detailed information of selected SNPs in each gene.

most.sig.genes

a character vector of genes selected by ARTP2. They are the most promising candidates, although their statistical significance is not guaranteed.

deleted.snps

a data frame containing SNPs excluded from the analysis and their reasons.

deleted.genes

a data frame containing genes excluded from the analysis because they are subsets of other remaining genes.

options

a list of options used in the analysis. See options

test.timing

timing information (in sec)

accurate

TRUE if options$nperm is large enougth to accurately estimate p-values, i.e., if the criteria sqrt(pvalue*(1-pvalue)/nperm)/pvalue < 0.1 is satisfied.

Details

An ARTP2 test has two major steps in testing an association. The first step applys data clean criteria and creates necessary and reusable statistics, which can be time-consuming for large pathways. The second step performs the testing procedure to estimate the pathway or gene-level p-value. warm.start focuses on the second step.

The first step can be done by using sARTP or rARTP if their options$only.setup is set as TRUE. Their output object, setup, can be used as the first argument of warm.start. With warm.start, users can try different configurations to perform various tests allowed by the ARTP2 framework, but avoid long waiting time for data cleaning. Commonly used options in setup$options include method, inspect.snp.n, inspect.gene.n, nperm, etc.

Note that both sARTP and rARTP can produce the final p-value directly if options$only.setup is FALSE.

The setup is supposed to have all components defined in sARTP and rARTP. If nperm is NULL, then it will be set as setup$options$nperm. The users can also pass lambda if a second round genomic control is needed. However, unlike in sARTP, lambda here can only be a single numberic number rather than a vector. Options nperm and lambda are the most useful ones in using warm.start so we highlight them in the interface. Users can modify any option values in setup$options directly to get more controls of the testing procedure. See options for more details about how to set setup$options.

Except for setup$options, all other components in setup should not be modified by users.

References

Zhang H, Wheeler W, Hyland LP, Yang Y, Shi J, Chatterjee N, Yu K. (2016) A powerful procedure for pathway-based meta-analysis using summary statistics identifies 43 pathways associated with type II diabetes in European populations. PLoS Genetics 12(6): e1006122

Yu K, Li Q, Bergen AW, Pfeiffer RM, Rosenberg PS, Caporaso N, Kraft P, Chatterjee N. (2009) Pathway analysis by adaptive combination of P-values. Genet Epidemiol 33(8): 700 - 709

Zhang H, Shi J, Liang F, Wheeler W, Stolzenberg-Solomon R, Yu K. (2014) A fast multilocus test with adaptive SNP selection for large-scale genetic association studies. European Journal of Human Genetics: 22, 696 - 702

See Also

sARTP, rARTP, options

Examples

# NOT RUN {
## firstly, run the example in sARTP
## users can adjust the second round inflation in warm.start
## the first round inflation can be study-specific and adjusted in rARTP 
## or sARTP

library(ARTP2)
study1 <- system.file("extdata", package = "ARTP2", "study1.txt.gz")
study2 <- system.file("extdata", package = "ARTP2", "study2.txt.gz")
pathway <- system.file("extdata", package = "ARTP2", "pathway.txt.gz")
chr <- 1:22
nchr <- length(chr)
fam <- vector("character", nchr)
bim <- vector("character", nchr)
bed <- vector("character", nchr)
for(i in 1:nchr){
  fam[i] <- system.file("extdata", package = "ARTP2", paste("chr", chr[i], ".fam", sep = ""))
  bim[i] <- system.file("extdata", package = "ARTP2", paste("chr", chr[i], ".bim", sep = ""))
  bed[i] <- system.file("extdata", package = "ARTP2", paste("chr", chr[i], ".bed", sep = ""))
}
reference <- data.frame(fam, bim, bed)
options <- list(inspect.snp.n = 2, nperm = 1e4, 
                maf = .01, HWE.p = 1e-6, 
                gene.R2 = .9, 
                id.str = "unique-pathway-id", 
                out.dir = getwd(), save.setup = FALSE)
                
## different inflation factors are adjusted in two studies
## first round adjustment
lambda <- c(1.10, 1.08)
ncases <- list()
ncontrols <- list()
ncases[[1]] <- c(9580, 2591)
ncontrols[[1]] <- c(53810, 3052)
ncases[[2]] <- 7638
ncontrols[[2]] <- 54319

family <- 'binomial'

## do not run permutation
options$only.setup <- TRUE
## the first round study-specific inflation is adjusted as lambda = c(1.10, 1.08)
# setup <- sARTP(summary.files = c(study1, study2), pathway, family, reference, lambda, 
#                ncases, ncontrols, options = options)

## the two rounds of inflation is adjusted as lambda2 = c(1.17370, 1.15236)
lambda2 <- lambda * 1.067
## run permutation to calculate p-value
options$only.setup <- FALSE
# ret1 <- sARTP(summary.files = c(study1, study2), pathway, family, reference, lambda2, 
#               ncases, ncontrols, options = options)

## or adjust the second round of inflation in warm.start
# ret2 <- warm.start(setup, lambda = 1.067)

# two ways of inflation adjustment should give same results
# ret1$pathway.pvalue == ret2$pathway.pvalue

###############################################################
###############################################################
## modify or specify the method
# setup$options$method <- 2
# setup$options$inspect.snp.n <- 3

## nthread = 2 for Linux only
## nthread will be reset to 1 under Windows and Mac OS
# ret3 <- warm.start(setup, nperm = 1e5, nthread = 2)

# }