README.md

# 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](mailto:stefan.kleeberger@gmail.com) (Programmer), [Dr. Benno Pütz](mailto:puetz@psych.mpg.de) (Technical advisor & Supervisor),  [Prof. Dr. Bertram Müller-Myhsok](mailto:bmm@psych.mpg.de) (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](mailto:stefan.kleeberger@gmail.com).

## 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](http://pngu.mgh.harvard.edu/~purcell/plink/data.shtml#bed)

and

- [PLINK phenotype file documentation](http://pngu.mgh.harvard.edu/~purcell/plink/data.shtml#pheno)

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
```