Repository files navigation

Find the full package documentation including examples and articles here:Multivariate MAPIT Documentation.

This R package is a generalization of theMAPITimplementation by Crawford etal. (2017)¹ for any number of traits as described by Stamp et al. (2023)².The univariate MAPIT test for marginal epistasis is implemented as the specialcase of running multivariate MAPIT with a single trait.

mvMAPIT is implemented as a set of R and C++ routines, which can becarried out within an R environment.

Epistasis, commonly defined as the interaction between genetic loci, is known toplay an important role in the phenotypic variation of complex traits. As aresult, many statistical methods have been developed to identify genetic variantsthat are involved in epistasis, and nearly all of these approaches carry outthis task by focusing on analyzing one trait at a time. However, because of thelarge combinatorial search space of interactions, most epistasis mappingmethods face enormous computational challenges and often suffer from lowstatistical power.

Previous studies have shown that jointly modeling multiple phenotypes can oftendramatically increase statistical power for association mapping. Therefore, herewe present themultivariate MArginal ePIstasis Test (mvMAPIT) – amulti-outcome generalization of a recently proposed epistatic detection methodwhich seeks to detectmarginal epistasis or the combined pairwise interactioneffects between a given variant and all other variants. By searching for marginalepistatic effects, one can identify genetic variants that are involved inepistasis without the need to identify the exact partners with which the variantsinteract – thus, potentially alleviating much of the statistical and computationalburden associated with conventional explicit search based methods. Our proposedmvMAPIT builds upon this strategy by leveraging correlation structures betweentraits to improve the identification of variants involved in epistasis. Weformulate mvMAPIT as a multivariate linear mixed model and develop a multi-traitvariance component estimation algorithm for efficient parameter inference andP-value computation. Together with reasonable model approximations, our proposedapproach is scalable to moderately sized GWA studies.

Themultivariate MArginal ePIstasis Test is a multi-outcome extension of thestatistical framework MAPIT which aims to identify variants that are involved inepistatic interactions by leveraging the correlation structure of non-additivegenetic variation that is shared between multiple traits. The key idea behind theconcept of marginal epistasis is to identify variants that are involved inepistasis while avoiding the need to explicitly conduct an exhaustive search overall possible pairwise interactions. As an overview of mvMAPIT and itscorresponding software implementation, we will assume that we have access to aGWA study onN individuals denoted asD = {X,Y} whereX is anN x J matrixof genotypes withJ denoting the number of SNPs (each of which is encoded as{0,1,2} copies of a reference allele at each locusj) andY denoting aN x Dmatrix holdingD different traits that are measured for each of theNindividuals.

The goal of mvMAPIT is to identify variants that have non-zero interaction effectswith any other variant in the data. To accomplish this, we examine each SNP inturn and assess the null hypothesis that its corresponding variance component is zero. Inpractice, we use a computationally efficient method of moments algorithm called MQS from Zhou (2017)³to estimate model parameters and to carry out calibrated statistical tests withinmvMAPIT.

The package needs compilation but the released version can be installed fromCRAN.

install.packages("mvMAPIT")

R is a widely used, free, and open source software environment forstatistical computing and graphics. The most recent version of R can bedownloaded from theComprehensive R Archive Network(CRAN). CRAN provides precompiled binaryversions of R for Windows, macOS, and select Linux distributions thatare likely sufficient for many users' needs. Users can also install Rfrom source code; however, this may require a significant amount ofeffort. For specific details on how to compile, install, and manage Rand R-packages, refer to the manualR Installation andAdministration.

mvMAPIT requires the installation of the following R libraries:

• checkmate
• CompQuadForm
• dplyr
• foreach
• harmonicmeanp
• logging
• mvtnorm
• Rcpp
• RcppAlgos
• RcppArmadillo
• RcppParallel
• RcppSpdlog
• tidyr

The easiest method to install these packages is with the followingexample command entered in an R shell:

install.packages(c( 'checkmate',                     'CompQuadForm',                     'dplyr',                     'foreach',                     'harmonicmeanp',                     'logging',                     'mvtnorm',                     'Rcpp',                     'RcppAlgos',                     'RcppArmadillo',                     'RcppParallel',                     'RcppProgress',                     'RcppSpdlog',                     'testthat',                     'tidyr',                     'truncnorm'),                     dependencies = TRUE);

Alternatively, one can alsoinstall R packages from thecommand-line.

The easiest way to install the package from sources is to change intothe directory of mvMAPIT and runR CMD INSTALL . --preclean. The--preclean flag makes sure that the latest state is run.

The code in this repository assumes that basic Fortran and C++ libraries and compilers are already set up on the running personal computer orcluster. If not, the mvMAPIT functions and necessary Rcpp packages willnot work properly. A simple option is to usegcc. macOS users may use this collection byinstalling theHomebrew package manager andthen typing the following into the terminal:

brew install gcc

Note that mvMAPIT takes advantage ofOpenMP, anAPI for multi-platform shared-memory parallel programming in C/C++. Thisis to speed up the computational time of the modeling algorithm.Unfortunately, macOS does not currently support OpenMP under the defaultcompiler. A work around to use OpenMP in R on macOS can be foundhere.mvMAPIT can be compiled without OpenMP, but we recommend using it ifapplicable for scalability.

• When your compiler changes, some R package dependencies might need to be recompiled. This is likely the case if the compilation error explicitly names an R package in the local library.

• On macOS, you might need to runbrew reinstall z3 to fix'libz3.4.11.dylib' (no such file) related errors (clang issues).

• For extra tips on how to run C++ on macOS, please visithttps://seananderson.ca/2013/11/18/rcpp-mavericks.html.

• For tips on how to avoid errors dealing with-lgfortran or-lquadmath, please visithttps://thecoatlessprofessor.com/programming/rcpp-rcpparmadillo-and-os-x-mavericks-lgfortran-and-lquadmath-error/.

For questions or concerns with the MAPIT functions, please contactLorin Crawford orJulian Stamp.

We appreciate any feedback you may have with our repository and instructions.