## Installation for KmerSVM Tool from Galaxy ToolShed

Christopher Fletez-Brant, Dongwon Lee, Andrew McCallion and Michael A. Beer

KmerSVM can be downloaded from the Galaxy Tool Shed, located at Dummy Link. To install KmerSVM, download files from LINK BELOW. Untar/zip the archive and move the resulting file 'kmersvm' to '~/galaxy-dist/tools/'.

## Dependencies

### Mac Users:

1. Xcode (Mac App Store)
2. Fortran compiler (http://gcc.gnu.org/wiki/GFortran/)

### Everyone:

1. Swig (http://www.swig.org)
2. Numpy (numpy.scipy.org)
3. Shogun Toolbox, v0.9.3 - v1.10 (http://www.shogun-toolbox.org/)
4. Bitarray (http://pypi.python.org/pypi/bitarray/)
5. R (http://www.r-project.org)
6. ROCR R Package (Available through CRAN)

Note that for binaries are provided for Mac users. However, if difficulties in installation are encountered, it may be beneficial to compile the Fortran compiler from source. Additionally, be sure to add the location of your Shogun installation to the PYTHONPATH.

Further, KmerSVM has been tested on Python 2.6, 2.7 on Linux and Mac OS X. At this time KmerSVM has not been tested on Windows.

## Required Files

For efficient access to genome-wide data "Generate Null Sequence" and "Sequence Profiles" rely on access to binary files (indices) generated by using the script 'nullseq_build_indices.py'. Download the *.tar or *.zip files for each genome to be analyzed. To create indices for a specific genome, call nullseq_build_indices.py as follows:

      python nullseq_build_indices.py

Next copy nullseq_indices.loc.sample to tool-data/nullseq_indices.loc and add the path to the created indices following the instructions included in that file.

To generate FASTA files for training or scoring purposes, KmerSVM uses the built-in tool "Fetch Sequences", which looks for genomes in *.nib or *.2bit format. Download genomes related to your data and update the 'alignseq.loc' file to include the location of these genomes according to directions in that file. FASTA files can also be provided by the user.

Move the file sample_roc_chen.png to the 'tool-data' file.

## tool_conf.xml

Add the following lines to tool_conf.xml to make tools visible in Galaxy:

        <section name="SVM Tools" id="kmersvm">
          <tool file="kmersvm/classify.xml"/>
          <tool file="kmersvm/nullseq.xml"/>
          <tool file="kmersvm/rocprcurve.xml"/>
          <tool file="kmersvm/train.xml"/>
          <tool file="kmersvm/split_genome.xml"/>
          <tool file="kmersvm/seqprofile.xml" />
        </section>

## Tool Tests

To run tests on the tools "Train SVM", "Score Sequences of Interest" and "Split Genome", move the following files to the 'test-data' directory:

- classify_output.out
- classify_test.fa
- kmersvm_output_weights.out
- test_positive.fa
- test_negative.fa
- test_weights.out
- train_predictions.out

IDs for KmerSVM tests can be found by calling run_functional_tests.sh with the '-list' flag.

## Non-Galaxy-Based Usage

The KmerSVM suite can be ran without using the Galaxy framework. Each tool exists as a standalone Python script (all located in /scripts) which can be called from the command line. Specific documentation can be found within each tool's Python file, or by calling the script with no arguments. A general workflow can be found in INSERT_PAPER_TITLE_HERE, which can be followed by calling each of the relevant Python scripts as outlined below, with the exception that users will have to provide needed FASTA files themselves.

A simple worflow for the KmerSVM suite is as follows:

1. python nullseq_build_indices.py <TARBALL OR ZIP OF GENOME> <GENOME BUILD>
2. python nullseq_generate <INPUT FILE> <GENOME BUILD> <PATH TO INDEX FILES>#This assumes no negative data sets. Output will need to be converted to FASTA. Skip if negative data is provided.
3. python kmersvm_train.py <POSITIVE FASTA> <NEGATIVE FASTA> #Outputs will be WEIGHTS, PREDICTIONS
4. python split_genome.py <INPUT BED FILE> #Skip if already have a list of regions you want to test. Output is TEST_SEQS, which will need to be converted to FASTA.
5. python kmersvm_classify.py <WEIGHTS> <TEST_SEQS>

Additionally, for any BED file, sequence composition (in terms of length, GC content and repeat fraction) can be obtained by calling 'make profile' as follows:

python make_profile.py <BEDFILE> <BUILDNAME> <BASE_DIR> <OUT_FILE>

Note that each tool has its own parameters, the manipulation of which allow the user to further customize their analysis. To learn more about a particular tool, simply call it without passing it any arguments.