############################################
# GNUMAPS
# developed in jlab.bu.edu (cjhong@bu.edu)
############################################

1. Objectives
The GNUMAP is a next generation sequence alignment algorithm. By integrating base quality into a dynamic programming framework and also allowing suboptimal alignments, it achieves more sensitive and higher quality of mapping results. It is very general mapper that can be used any type of reads generated by most NGS platform, molecular types(dna,rna seq), library type, and any genome size. The GNUMAPs is a pipeline to make GNUMAP more user-friendly. Some quality control feature is provided. It supports paired end reads, unstrand, strand lib, bisulfite mapping, RNA editing discovery, and pileup process for postprocess analysis.


2. Requirements
-Make sure that -lpthreads installed
-install OpenMPI(mpic++), zlib, parallel, and libpng. For debian distribution, e.g., Ubuntu, try "sudo apt-get install lam4-dev libmpich-dev libopenmpi-dev libpng12-dev zlib1g-dev libncurses5-dev libncursesw5-dev parallel"
-Python 2.6+ required to install some quality control softwares

3.1 Installation
Download gnumaps.tar.gz
unzip gnumaps.tar.gz into your application directory (e.g, ~/apps)
tar zxvf gnumaps.tar.gz -C ~/apps
cd apps/gnumaps
GNUMAPS=/home/johndoe/shared/apps/gnumaps

When you run any one of following command, we recommend you append "2>&1 | tee install.log" at the end of the command.

3.1.2 if you want to install gnumap only
./install_gnumaps.sh 2>&1 | tee install.log

3.1.3 if you want to install gnumap + quality control + blat
./install_gnumaps.sh qc blat

3.1.4 if you want to install gnumap + blat
./install_gnumaps.sh 1 blat 3 $MACHTYPE

3.1.5 if you want to install gnumap + qc
./install_gnumaps.sh qc

3.1.6 if you want to install gnumap (MPI version) + qc
./install_gnumaps.sh qc 2 mpi
-We recommend you install pthread gnumap only which is very efficient and enough to analyze most of genomes.


add gnumaps installation directory to your shell script configuration file. For example, add
export GNUMAPS=$HOME/apps/gnumaps
to $HOME/.bash_profile or $HOME/.profile for bash

3.2 Uninstallation
./install_gnumaps.sh


4. Example
cd $GNUMAPS/examples
4.1 bisulfited read toy example (unstranded lib and paired end reads)
./ex_run_bsr.sh
cd $GNUMAPS/examples/exp/toyBSR (to check the output files)

4.2 searching RNA editing events across both genome strands (watson and crick)
./ex_run_a2i.sh
cd $GNUMAPS/examples/exp/toyRNAe (to check the output files)

4.3 Using a known transcriptome annotation, you may increase the sensitivity of RNA-Seq mapping,

4.3.1 To achieve this, you need install BLAT in the installation setup.

4.3.2 download an annotation file from UCSC. For example, for mm9, try 

http://genome.ucsc.edu/cgi-bin/hgTables?hgsid=341785609&clade=mammal&org=Mouse&db=0&hgta_group=genes&hgta_track=refGene&hgta_table=refFlat&hgta_regionType=genome&position=&hgta_outputType=primaryTable&hgta_outFileName=refFlat.txt.gz

4.3.3 refer to the guideline (http://useq.sourceforge.net/cmdLnMenus.html#MakeTranscriptome) to generate a set of transcriptome sequences in FASTA file format where all introns are removed. Make the transcriptome file size smaller than 3.5GB.

4.3.4 you specify the transc FASTA file in full path to --transc.

5. Running options
Usage: gnumaps.pl [options]
 --help         Displays this information
 --genome       FASTA format reference genome file[required]
 --transc   	FASTA format reference transcriptome files (Refer to README 4.3)
 --pair_1       if pair-end read specify _1.txt
 --pair_2       if pair-end read specify _2.txt
 --single       if single-end read specify the read file here[read1,2 or single required]
 --qcontrol     quality control enabled and make sure that all necessary programs are ready[0]
 --adaptor      adaptor sequence
 --adaptor2     adaptor sequence if the one for 2nd is different
 --lib_type     it can be [unstrand], cr1 or wt1
 --read_type    it can be [dna] or rna
 --phred_offset speicify read quality offset. note that set to 0 if reads are in fasta file format (0, [33], or 64)
 --per_dist     if paired read, specify a distance between two reads[300]
 --map_quality  specify the mapping option, e.g., sensitive,balanced,fast
 --nt_conv      if the read is bisulfited or you want to explore rna edits, specify bs(bisulfited reads) or a2i (to discover RNA edit events (A-to-I))
 --skip_blat    if you want to skip blat mapping, set to 1 [0]
 --pileup       if you want to convert sam to bam file, set to 1 or 2(flip 2nd read to the watson strand for a better representation in IGB) [0].
 --num_threads  the number of cores to enable[1]
 --outdir       an output directory[required]
 --debug        set to 1 if you want to perform in a debug mode

5. Notes
In order to align reads to human genome size, we strongly recommend that a user trys GNUMAPS on the desktop computer with 30GB RAM or higher.

6. Reference

8. Contact
cjhong@bu.edu
