CoMIK : Conformal MultiInstance Kernels
CoMIK is a novel approach for sequence comparison that enables larger positional freedom than most of the existing approaches, can identify a possibly dispersed set of features in comparing variablelength sequences in a discriminative setting (classification). CoMIK identifies not just the features useful towards classification but also their locations in the variablelength sequences aided by recently introduced visualization techniques.
Manuscript authors: Sarvesh Nikumbh, Peter Ebert, Nico Pfeifer
If you use CoMIK, please cite us as follows:
Nikumbh S, Ebert P, Pfeifer N: All Fingers Are Not the Same: Handling VariableLength Sequences in a Discriminative Setting Using Conformal MultiInstance Kernels. In 17th International Workshop on Algorithms in Bioinformatics (WABI 2017). Schloss Dagstuhl; 2017. [Leibniz International Proceedings in Informatics, vol. 88]
More information (e.g., Bibtex entry) is available at: http://drops.dagstuhl.de/opus/volltexte/2017/7645/
bioRxiv DOI: https://doi.org/10.1101/139618
Requirements:
 MATLAB 9.0.0.341360 (R2016a) [We developed CoMIK using this version of MATLAB (R2016a). Compatbility checked with version 8.6 (R2015b)]
 Python 2.7 or higher
 SHOGUN Release version 3.2.0 [See issue #7 (issues/7) in this regard. CoMIK also works with the latest SHOGUN version 6.0.0]
For the visualizations, the following R (R version 3.4.0) packages are needed
 Lattice (lattice_0.2035)
This repository contains Matlab code for the project CoMIK. The various ".m" files define corresponding Matlab functions. We use MKL implementation from Shogun's modular interface for Python. The Python script mkl.py handles solving of the MKL problem.
If you have MATLAB installed, you can run CoMIK from inside MATLAB. But, in case you do not have MATLAB installed, we provide an executable version for which you would additionally need the MATLAB Runtime. MATLAB Runtime can be downloaded from https://mathworks.com/products/compiler/mcr.html . We recommend getting version 9.0 (R2016a) installed. If that does not work, 8.6 (R2015) would also work.
Installation:
git clone https://github.molgen.mpg.de/snikumbh/comik.git
cd comik
sh install.sh
 Install SHOGUN
 Only if you are planning to use the executable, install MATLAB Runtime. Follow the instructions for installation of the MATLAB Runtime; install at any location of your choice on the disk. Once the dependencies are handled, e.g., SHOGUN, MATLAB runtime etc., and the paths are set, you can test CoMIK as follows
a) sh test_install.sh matlab
OR
b) sh test_install.sh executable <your_MCR_path_here> <version>
With (a), CoMIK is tested from inside of MATLAB, and with (b), the CoMIK executable is tested. Example command to test the executable for version 9.0 (R2016a)
sh test_install.sh executable /usr/lib/matlab9.0 v90
Usage:
If you have MATLAB, an example function call from inside Matlab is as follows:
For simulated dataset 1 provided in the folder sample_data/simulated_dataset1
comik_wrapper('configcomik.txt');
If not, you can use the executable as follows:
# ./run_CoMIK_v90.sh <MATLAB_Runtime_location> <config_file>
# for version 9.0 (R2016a)
./run_CoMIK_v90.sh /usr/lib/matlab9.0 configcomik.txt
OR
# for version 8.6 (R2015b)
./run_CoMIK_v86.sh /usr/lib/matlab8.6 configcomik.txt
where /usr/lib/matlab9.0
could be replaced with the location of the MATLAB Runtime on your machine. Additionally, when required, you can add your own paths to the LD_LIBRARY_PATH
environment variable in the file run_CoMIK_v86.sh
or run_CoMIK_v90.sh
(for example, the path for shogun can be added here).
CoMIK requires two FASTA files as input  the first FASTA file containing sequences in the positive class; the second FASTA file containing negative class sequences. Other params are explained below.
Values for the following parameters are required to be set:
 positive FASTA filename [type: str]
 negative FASTA filename [type: str]
 number of positive sequences [type: int]
 number of negative sequences [type: int]
 Indices of the test sequences [type: int, given as a Matlab vector]
 outputfoldername [type: str]
The rest have default values, which can be good starting points.
Param name  type  default value  Additional comments 

oligomerlengthsasvector  int  [2]  Required for the ODH representation. Recommended values: 2 or 3 (suffices). Passing a vector [2 3] will run comik first with oligomerlength 2 followed by an independent second run with oligomerlength 3. Further, see Note 2 below 
maximumdistance  int  50  Required for the ODH representation. Typically, a maximum distance of 100 basepairs suffices even if the segmentsize is larger 
segmentsize  int  100  See Note 1 below 
numberofclusters  vector of ints  [2 5]  Recommended maximum number of clusters: 7 
sigmavaluesforGaussiantransformation  vector of floats  10.^[1:1:2]  typical values: 10.^[1:1:2] which is Matlab notation to obtain the vector [0.1, 1.0, 10.0, 100.0]] 
costvaluesforSVM  vector of floats  10.^[3:1:3]  typical values: 10.^[3:1:3] 
mklNorm  int/float  2.0  typically 1.0 or 2.0 
numberofinnerfolds  int  10  
numberofouterfolds  int  5  
whetherToPlotHeatmap  str  'No'  Possible values: 'Yes' or 'No'; Set 'Yes' only if all sequences are of the same length. 
whetherToVisualizeWVector  str  'Yes'  Possible values: 'Yes' or 'No'; Set 'Yes' when you wish to have the distancecentric kmer visualization. 
debugLevel  int  2  Possible values: [0, 1, 2]. Value 0 makes comik completely silent, and 2 makes it maximally verbose. Value 1 may be used in the future. 
debugMsgLocation  int/str  1  Value 1 denotes the command prompt, else specify a filename, say 'runLog.txt'. This file is written for each outer fold separately. 
computationVersion  str  'Looping'  Possible values: 'Looping' or 'AccumArray'. 'Looping' is faster and preferred/recommended for large datasets when 'AccumArray' can be memory intensive. 
The comik_wrapper
function handles creation of and running outer crossvalidation folds (as part of nested crossvalidation). The supplied indices of the test sequences, or test_indices
are then used to note the proportion of positives and negatives from the whole set that is to be treated as unseen test examples. The given set of sequences are then shuffled before splitting them into training and unseen test examples as per the specified proportions. The indices of the samples treated as unseen test examples is also written to disk per outer fold (filename: testIndices.txt).
Note 1: In case you are interested in performing a quick, exploratory run using CoMIK on your data, kindly note that depending on the number of sequences in the collection and their lengths, if there are many very long sequences, a small segmentsize may lead to very high number of segments in total thereby increasing the computation time which may be prohibitive for this initial run. Hence, for such an initial run, the following values are recommended:
oligomerlength: [2]
maximumdistance: min(segmentsize, 50)
numberofclusters: [2 5]
segmentsize: 100 or 200
Note 2: Kindly note that oligomerlengths of 3 or larger than 3, depending on the number and length of the sequences, and segmentsize used, can lead to very highdimensional vectors which can be memoryintensive.
Note 3: Presently, CoMIK uses MATLAB parforloop to execute the outer crossvalidation folds in parallel.
During the run,

CoMIK omits the sequences whose lengths are shorter than the segmentsize specified from the run. It reports the number of sequences that got omitted, their FASTAIds in a separate file named
omittedFastaIds.txt
per outer fold separately. 
the following files are written to the disk per outer fold at any intermediate stage of the pipeline. Most of these are used by the pipeline itself in its subsequent stages.
 Run summary file: The resultString is also written to the summary file which is characterized by the segmentsize and oligomerlength. The summary file is typically named: 'runSummary_segmentsizeX_oligoLenY.txt' where X and Y are as set for the pipeline run.
 The various train and test kernels (as .csv files)
 The weight vectors corresponding to the kernels
 The support vector indices
 The alpha values
 SVM bias value
 Kernel weights upon performing MKL
 The visualizations of the sequence logos
 Heatmaps if the flag has been set
For comments and questions, feel free to report an issue