"Taxy" MATLAB/Octave toolbox for taxonomic profiling of metagenomes
===================================================================

1. Introduction
---------------
Taxy is a freely available toolbox for taxonomic profiling of large metagenomic
data sets, implementing the mixture modeling approach presented in Meinicke et
al. (submitted).
To be able to use the Taxy toolbox, either the MATLAB software
(http://www.mathworks.com/) or the freely available MATLAB clone Octave
(http://www.gnu.org/software/octave/) have to be installed.
If you are not familiar with script languages, programming and shell commands,
please consider downloading the freely available Taxy tool for Microsoft
Windows (XP and above), which comes with an easy-to-use graphical user
interface. The Taxy tool can be found at

	http://gobics.de/peter/taxy/

2. Installation
---------------
After downloading, unpack the Taxy toolbox archive. The 'TaxyToolbox' folder
contains Matlab/Octave scripts for the Taxy subroutines, pre-compiled binary
files for fast DNA word counting and a folder named 'Data' with pre-calculated
DNA word count profiles and taxonomical annotation for many prokaryotic
organisms. Furthermore, a FASTA file with sample data (human gut sample “In-D,
Healthy Human Adult Male” from Kurokawa et al., DNA Research, 2007) will be
extracted into the 'Data' folder.
The toolbox provides pre-compiled binary files ("mex" files) for Windows and
64-bit Linux. If your system is different from this, you may have to compile an
appropriate binary using the MATLAB/Octave compiler. For this you have to call

	mex countWordsMexPM.c
	
from the MATLAB/Octave command prompt. Note that in the case of Octave and Linux
the 'octave-headers' have to be installed. Please also refer to the 
documentation of your MATLAB/Octave installation.

3. Usage
--------
3.1 - Start MATLAB/Octave and change to the TaxyToolbox directory or add the
corresponding toolbox path using 'addpath'. Type 'help TaxyMain' to get an
overview of the use of the Taxy main routine or 'TaxyDemo' to start a guided
example of the Taxy toolbox using sample data. The demo script also compiles
the fast DNA word counting routine using the MATLAB/Octave compiler.
Note that MATLAB and Octave are not fully compatible, thus some trade-offs had
to be made during programming and the behaviour of Taxy differs in some details.
Please feel free to adapt the Taxy source code according to your requirements.

3.2 - Call 'TaxyMain' with the configuration of your choice. Note that Taxy only
accepts multiple FASTA DNA files (http://www.ncbi.nlm.nih.gov/BLAST/fasta.shtml)
as input metagenome data. The word length parameter may be selected in the range
from 6 to 8 nucleotides, the default word length is 7. Note that for word length
8 at least 2 GB available working memory are necessary.
By default, Taxy only uses quadratic programming (QP) as optimization method,
however, by requiring three output arguments in the TaxyMain call, you can force
Taxy to additionally perform expectation-maximization (EM). The results of the
EM method depend on the number of EM iterations, which can be adapted in the
subroutine 'TaxyWeights'.
Depending on the size of the input, the computational power of your machine and
the choice of the Taxy optimization method, the Taxy computation will take
between a few seconds and several minutes.

3.3 - After successful computation of the taxonomic profile, Taxy will output
comma-separated value (CSV) files in the folder specified by the third TaxyMain
input argument (if permissions allow so). If no such folder is specifed, the
folder will be created in the directory containing the sample file. The CSV
files contain the taxonomical distribution according to the different taxonomic
levels, whereby the first column represents the taxon and the second column
represents the estimated fraction of this taxon in the input metagenome data.
The subroutine 'calcTaxDistribution' can be modified easily to let Taxy display
bar plots showing the estimated taxonomical distribution of the metagenome on
different taxonomic levels (phylum, class, order, family).

4. Updating data
----------------
The Taxy toolbox is based on pre-calculated DNA word count profiles of currently
1013 prokaryotic organisms from the KEGG database including their taxonomical
annotations (files in the 'Data' folder). To ensure the best profiling quality,
we will occasionally update the profile and annotation files and provide them
for download.

5. Comments and questions
-------------------------
If you have any Taxy-related comments, feature requests, bug reports or
questions please mail to 

	taxy@gobics.de

