kleEpistasis

Brute-force 3-way Interaction calculation for genetic studies

Welcome to kleEpistasis. A tool for performing 3-way genetic interaction analysis.

Contact: Stefan Kleeberger (Programmer), Dr. Benno Pütz (Technical advisor & Supervisor), Prof. Dr. Bertram Müller-Myhsok (Supervisor), Max Planck Institute of Psychiatry, Munich, 2016

Still in development!

This tool recently reached the status of BETA. The core functionality is hereby given. If there is any interest in using this tool, I will continue adding features to it. If you are interested in working with this tool and need assistance, please leave me a note.

Compilation & needed technologies

Prerequisites

You will have to have at least a CUDA 2.0 capable device (if not 3.5 you need to change the Makefile from sm_35 to sm_20)
the complete CUDA toolkit installed
You need (at the moment) a greater amount of memory (for 5000 SNPs & 1000 Individuals, we needed ~20 GB)
At least 8 cores

Preparations

Candidate SNPs or at least pre-selected SNPs. Genome-wide won't be feasible ... yet.
make appropriate changes in the Makefile (see below)
make appropriate changes in the helperzz/build.sh file
located in the kleEpistasis directory, you can either run make or, ./helperzz/build.sh which is a small script to create the needed filesystem structure and compile using multiple threads simultaneously
The resulting binary will be located in bin/kleEpistasis.

Changes you may need to make in the Makefile

Please customize your Makefile as you need. You may want to change (friendly reminder: in sh shells there must not be any whitespace in VARIABLE=VALUE assignments)

the location of your CUDA compiler nvcc (line 5)
change the compute capability according to your device (e.g. m_35 to sm_20, line 5)
the location of your CUDA library (line 6)
add debugging flags -g -G to OPT (line 7)
and anything else you want to change, as long as you know what you are doing.

What should my data look like?

In order to perform brute-force statistical 3-way interaction tests on SNP data with kleEpistasis you will have to provide your genotype data in PLINK binary format and a phenotype in PLINK alternate phenotype format. Please see

PLINK bed file documentation

and

PLINK phenotype file documentation

for more information regarding file formats.

Flags:

REQUIRED

-path [path] Absolute or relative path to plink files in binary format (.bed .bim .fam) without file extension

-pathPheno [path] Absolute or relative path to plink alternate phenotype file with file extension

-outPath [path] Absolute or relative path to file where results will be written with file extension (.csv)

-device [0,1,...] GPU identifier, starting from 0 for first Graphics Card increasing in whole numbers

-blockSize [2,3,...] parameter for optimizing runtime. See explicit paragraph beneath

-threads [1,2,...] Number of threads to process results. See explicit paragraph beneath

-alphaPercent ]0.0;50.0[ Significance level for two-sided test. Allowed values: ]0.0;50.0[

OPTIONAL

-pheno [0,1,...] If your phenotype file contains multiple phenotypes, you can use this flag to specify which phenotype should be used. If you skip the -pheno flag, the first phenotype will be used (equivalent to -pheno 0). The second phenotype has index 1, the third index 2 and so forth...

-testBlockSize 1 This will start a test-run with only one sub-matrix to be calculated. Use this flag to reduce runtime to test for the best possible value for -blockSize This will not create ANY results!

Further explanations on flags

-blockSize: If you are familiar with CUDA, you know what it is about. Otherwise you needn't get too deep into this. All you need to know is that this parameter has to be found by trial and error. Use the -testBlockSize 1 to reduce runtime dramatically and try different values for blockSize We achieved best results with -blockSize 4 on a NVIDIA Tesla K40

-threads: Results will be processed in the background by the CPU while the GPU creates new results. Depending on your CPU und Graphics Card, the GPU has to wait for the CPU to finish before copying the next results. To resolve this the task is split into chunks and processed by one thread each. We used an Intel(R) Xeon(R) CPU E5-2630 v3 @ 2.40GHz combined with a NVIDIA Tesla K40 and 8 threads (-threads 8) without encountering wait time. The program will altogether create n+2 threads when n is the number passed via the -threads flag.

General

Memory:

For a run on 5000 SNPs and 1000 Individuals, you need at least 20GB of RAM

Execution time:

We were able to perform a run on 5000 SNPs and 1000 Individuals, on an Intel(R) Xeon(R) CPU E5-2630 v3 @ 2.40GHz combined with a NVIDIA Tesla K40 in approx. 2 hours

Result file:

The result file specified with -outPath has 4 columns: Position_SNP1, Position_SNP2, Position_SNP3, Calculated_Value and as many rows as significant results have been found.

Example calls:

For performing a runtime test:

./bin/kleEpistasis                                  \
    -path /home/testuser/testdata/plink             \
		-pathPheno /home/testuser/testdata/pheno.txt    \
		-outPath /home/testuser/results/testDataRes.csv \
		-device 0                                       \
		-blockSize 4 -threads 8                         \
	  -alphaPercent 5 -testBlockSize 1

For performing a complete run:

./bin/kleEpistasis                                  \
    -path /home/testuser/testdata/plink             \
		-pathPheno /home/testuser/testdata/pheno.txt    \
		-outPath /home/testuser/results/testDataRes.csv \
		-device 0                                       \
		-blockSize 4 -threads 8                         \
		-alphaPercent 5

kleEpistasis/README.md