MDROpenCL Files

MDRopencl README
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

MDRopencl Copyright 2011 James Rudd
jrudd (at) nccu (dot) edu


MDRopencl is an OpenCL implementation of Multifactor Dimensionality Reduction 
(MDR) geared towards execution on AMD and NVIDIA GPUs. For more information 
on MDR visit epistasis.org and for the latest details regarding OpenCL visit
http://www.khronos.org/opencl/ 

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
Program Description:

MDRopencl operates on input files compatible with the original MDR: a tab 
seperated text file in which the first line is a header row with variable names, 
the last column is the binary class variable (0 or 1), and the remaining columns
are SNP values coded as 0, 1, or 2.  When given a model size, MDRopencl 
exhaustively constructs all models of that size and returns the model with
the highest balanced accuracy. In order to assess overfitting, cross-validation
can be performed. Cross-validation results will choose the model with the 
highest testing balanced accuracy for a given partition. The final result will
be either: the model with the highest cross-validation consisteny; the model
with the hightest training accuracy; or the model with highest testing 
accuracy (selectable via the command line). The significance of the 
resulting model can be determined using permutation testing. If an 
alpha level is supplied, the testing will terminate when the alpha is 
exceeded or the number of permutations completes. 

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
Installation:

MDRopencl depends on the following:
	1. Video Driver with OpenCL support (available from nvidia.com or amd.com)
	2. PyOpenCL (http://mathema.tician.de/software/pyopencl)
	3. The python gmpy library

MDRopencl has officially been tested in Ubuntu 10.10 using the following for 
installation:
	sudo apt-get install python-pyopencl python-gmpy

Note: The above command will install the NVIDIA drivers even when AMD GPUs 
are present. If the AMD driver is needed, please follow the instructions in 
the PyOpenCL wiki.

-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
Usage: python MDRopencl.py [-h|--help] 
                 [-i FILENAME] INPUT FILE
                 [-m INTEGER] DIMENSIONALITY OF MODELS TO CONSIDER
                 [-p INTEGER] NUMBER OF PERMUTATIONS TO EMPIRICALLY DETERMINE SIGNIFICANCE
                 [-c INTEGER] number of CROSS VALIDATION partitions
                 [-s INTEGER] SEED to use for the random number generator
		 [-v] VERBOSE output
		 [-d INTEGER] ID of the GPU to use (only when multiple GPUs in a system)
		 [-a FLOATING POINT] The alpha level at which significance will be determined 
			using permutation testing. If the p-value exceeds this alpha, 
			the permutation will automatically be terminated. The default
			value is 1 which ensures that all permutations are completed.
		 [-b INTEGER] BEST model selection (only used when c > 1):
			-b 0 : Use Cross Validation Consistency (DEFAULT)
			-b 1 : Use Average Training Accuracy
			-b 2 : Use Average Testing Accuracy
		 [-B INTEGER] Maximum number of buckets to be stored in private thread memory
			Large value will force usage of global memory and slow computation
			Too low a value will increase loopig and slow computation
			The default value 81 is optimal for most modern GPUs
		 [-T INTEGER] Total number of THREADS to use on the GPU simultaneously.
			The default value is sufficient for most modern GPUs.


-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
Usage: python MDRopencl-multiGPU.py [-h|--help] 
                 [-i FILENAME] INPUT FILE
                 [-m INTEGER] DIMENSIONALITY OF MODELS TO CONSIDER
                 [-p INTEGER] NUMBER OF PERMUTATIONS TO EMPIRICALLY DETERMINE SIGNIFICANCE
                 [-c INTEGER] number of CROSS VALIDATION partitions
                 [-s INTEGER] SEED to use for the random number generator
		 [-v] VERBOSE output
		 [-a FLOATING POINT] The alpha level at which significance will be determined 
			using permutation testing. If the p-value exceeds this alpha, 
			the permutation will automatically be terminated. The default
			value is 1 which ensures that all permutations are completed.
		 [-b INTEGER] BEST model selection (only used when c > 1):
			-b 0 : Use Cross Validation Consistency (DEFAULT)
			-b 1 : Use Average Training Accuracy
			-b 2 : Use Average Testing Accuracy
   		 [-B INTEGER] Maximum number of buckets to be stored in private thread memory
			Large value will force usage of global memory and slow computation
			Too low a value will increase loopig and slow computation
			The default value 81 is optimal for most modern GPUs
		 [-T INTEGER] Total number of THREADS to use on the GPU simultaneously.
			The default value is sufficient for most modern GPUs.




This software is under active development.