----------------------
Contents of this file
----------------------

 * Introduction
 * Software Requirements
 * Hardware Requirements
 * Installation
 * Command Line Arguments
 * Maintainers

----------------------
Introduction
----------------------

JUMPm is a program for untargeted metabolite identification based on liquid chromatography and tandem mass spectrometry. The computer algorithm determines chemical formulas from either unlabeled or stable-isotope labeled metabolome data, and derives possible structures by predictive fragmentation during database search. JUMPm uses a target-decoy strategy based on the octet rule to estimate the rate of false discovery (FDR).  The user specifies a target FDR and JUMPm will filter the data to reach the target.  FDR is a critical measure of confidence which researchers can use in the analysis of their data. The program is written in perl and is designed for high performance parallel computing systems.
 
----------------------
Software Requirements
---------------------- 

The program is written in a combination of Perl, Java and R. It should run on every system with a Perl5, Java 1.7 interpreter and R 3.1.0. 
The minimum required Perl version should be Perl 5.8 or better.

Perl modules are needed:
    Parallel::ForkManager
	Class::Std
	Statistics::R
	Statistics::Basic
	Statistics::Descriptive
	Set::Partition
	Regexp::Common
	Number::Format

To install perl modules, please refer to:
http://www.cpan.org/modules/INSTALL.html
 

Java module:
CDK

R package has been included in the package of source code. 

The R source code is provided in the JUMPm folder. You need to rebuild it as follows:

1. tar -vxf R-3.1.0.tar
2. ./configure --with-readline=no
3. make

if you use default R environment, please change the $R_library variable in the main JUMPm script. 
 
----------------------
Hardware Requirements
---------------------- 

The program can be run on either high performance computing systme or a single server. 
 
To run on a cluster:
 Batch-queuing system: SGE, version 6.1u5, qsub and qstat
 32 GB memory on each node

To run on a single server
  32 GB memory
  2 GHz CPU processors with a minimum of 4 cores
  
----------------------
Installation
---------------------- 

The source code, database, sample data can be download from http://www.stjuderesearch.org/site/lab/peng

Database includes MASS_FORMULA_DB and STRUCTURE_DB.

After downloading the source code, you can put it in any working directory (e.g. /home/xxxx/JUMPm). 
**If you install the program on the cluster, the folder containing all source code is required to be accessible to each node. For example, you can put it on your local home directory. 

----------------------
Database setup
---------------------- 

The database can be download from http://www.stjuderesearch.org/site/lab/peng, including mass formula database and structure database.
After downloading databases, you can uncompress the two databases on your local directory.  


----------------------
Command Line Arguments
----------------------

Example:  ./jumpm •	jump -p <JUMPm parameter file> <MS/MS data file(s)>
-p <file> specifies a JUMP parameter file
<MS/MS data file(s)> specifies one or multiple MS/MS data file(s)

MS/MS data file(s) can be either .RAW or mzXML file. 
The mzXML file is converted from .RAW file by various programs, such as ReAdW or msconverter.
We suggest to use .mzXML file.

An example parameter file is provided in the package of source code. 

----------------------
Output
----------------------
1. metabolite feature
This table lists all features detected in each LC-MS run, which only contains information about features before performing database search. All features listed in this table are de-isotoped features. In other words, isotopic features are excluded in this table.
The format of metabolite feature table is shown below:
index	m/z	z	MS1 scan#	Intensity	S/N


2. formula table
This table lists all formulas detected for each each feature. The table lists the pairing information for a labeled dataset, whereas it use "N/A" for three columns, including N15 mass, C13 mass and Pscore. The target/decoy column shows whether the formula is a target or decoy hits. Two levels of target/decoy are used: the first type is only applied to the hits from user-specified database; the second is applied to all hits from theorectical formula database based on the octet rule.   
The format of metabolite feature table is shown below:
index	MS1	C12 mass	N15 mass	C13 mass	C12 intensity	N15 intensity	C13 intensity	S/N	Pscore	Formula	Target/Decoy

3. Spectrum-match table
This table lists all structure candidates for each formula. Three structure related features are added to this table: smiles, chemical name and Mscore.
The format of metabolite feature table is shown below:
index	MS1	C12 mass	N15 mass	C13 mass	C12 intensity	N15 intensity	C13 intensity	S/N	Pscore	Formula	Target/Decoy	structure (SMILES)	name	Mscore

4. Structure table
This table lists a unique structure candidate with the best Mscore for each formula. 
The format of metabolite feature table is shown below:
index	MS1	C12 mass	N15 mass	C13 mass	C12 intensity	N15 intensity	C13 intensity	S/N	Pscore	Formula	Target/Decoy	structure (SMILES)	name	Mscore

5. Intermediate files
All intermediate files can be found in the intermediate folder, called RAW_FILE_NAME.1.intermediate and RAW_FILE_NAME.1.

----------------------
Maintainers
----------------------

* To submit bug reports and feature suggestions, or to track changes, please contact:

 Xusheng Wang (xusheng.wang@stjude.org) and Junmin Peng (junmin.peng@stjude.org)
 
 