QAmiRSeq Files

#
#   QAmiRSeq: a strand aware pipeline for quick and accurate quantification 
#	of known miRNAs and isomiRs from high throughput small RNA sequencing
#

Copyright (C) 2016, Shanrong Zhao; Baohong Zhang

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
 any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.


#
## Prerequisite: installation of open sources
#
!!! Do make sure all the following prerequisites are meet
The following open source should be downloaded and installed
	1. download bowtie from https://sourceforge.net/projects/bowtie-bio/files/bowtie/0.12.7/
	2. install cutadapt packages https://pypi.python.org/pypi/cutadapt
Then add the executables to your PATH !!!
	
Perl modules required to be installed:
First, you can test whether these four modules installed by using the following command lines
	perl -e "use Config::Simple"
	perl -e "use Parallel::ForkManager"
	perl -e "use Compress::Zlib"
	perl oe "use MIME::Base64"
If you don't see any error message, you have them successfully installed. Otherwise, install them
	1. Config::Simple
	2: Parallel::ForkManager
	3: Compress::Zlib
	4: MIME::Base64
	
R packages required to be installed:
	reshape2, ggplot2, latticeExtra and scales

Note: Web browsers Firefox or Chrome are recommended, some features are not available in Internet Explorer. 

#
## Installation
#
#!!!
# It is assumed you're using bash shell. if NOT, please adjust the command line accordingly.
#  Especially, if you are using CSH, please set QAmiRSeq using
#    setenv QAmiRSeq QAmiRSeq_installation_Directory
#  Not  set QAmiRSeq QAmiRSeq_installation_Directory
#!!!	

#!!!
#You need to download and install QAmiRSeq from http://QAmiRSeq.sourceforge.net

#set environment variable to point to your installation directory
export QAmiRSeq=QAmiRSeq_installation_Directory

#add QAmiRSeq to your system path
export PATH=$QAmiRSeq:$PATH
#!!!


#
## Step #1: Preparation of miRNA/hairpin/mRNA/smallRNA database
#
After you download and unpack the QAmiRSeq package, you should 
	1. go to $QAmiRSeq/database folder 
	2. run create_database_util.sh to create databases for human/mouse/rat. 
This step will take a couple of hours (between 2-4hr)

!!! Don't move ahead until your database creation is successfully done !!!
You are encouraged to customize  create_database_util.sh  and create your own smallRNA
and mRNA databases. 

	
#
#Step #2: reads mapping, counting and summary
#
Please refer to $QAmiRSeq/demo_run and see how to analyse your own dataset. 
In essence, you need to prepare two files. 
	1. allIDs.txt: containing the list of samples that you want to analyze
	2. run.config: a control file in which you can instruct how the analysis is done

Run the pipeline:
	perl  $QAmiRSeq/QAmiRSeq.pl  allIDs.txt run.config


#
#Step #3: Generate an integrated report
#

Go to your output folder, and run a single command line
	$QAmiRSeq/QAmiRSeq-report.sh
	
NOTE: TAB delimited sample.annotation.txt Annotation is optional but it is strongly recommended.
      column #1:  sample_id
      column #2:  subject_id
      column #3--#n (optional)
 For clinical RNA-seq, samples from the same subject should be assigned to the same subject_id.
 QAmiRSeq requires the first and second columns correspond to sample and subject identifiers, respectively.
 A sample name should start with a letter, and does not contain any white space in the middle.

All analysis are accessible from index.html

#
# packaging (optional): if you want to share your results, you can package all needed files as below
# please run this "tar" command in the PARENT folder of your OUTPUT folder. 
# Replace "demo.tgz" AND "output" with appropriate names.
# The "output" folder name is specified in the run.config file when you run QAmiRSeq.pl script.
#
tar -zcvf demo.tgz --exclude='unmapped.csv' --exclude='mapped.csv' --exclude='trimmed' --exclude='bowtie_temp' --exclude='alignment' output/*
#tar -zcvf demo.tgz --exclude='unmapped.csv' --exclude='mapped.csv' --exclude='trimmed' --exclude='bowtie_temp' --exclude='alignment' *


########################################################################
P.S  Descriptions on data and figure summary files under project folder
     Results/Summary
########################################################################
Descriptions on main output files
#Delimited by "\t:\t"
=============================================================================
alignment	:	folder for miRNA read alignment
graphs		:	folder for all graphs

cutadapt.summary.txt	:	The summary for adapter trimming
isoform.Counts.csv	:	The read counts table for individual isomiRs
isoform.Counts.Mismatch.csv	:	The mismatch read counts table  for individual isomiRs
isoform.filter.Counts.csv	:	The read counts table for individual isomiRs with noisy reads filtered out
isoform.filter.Counts.Mismatch.csv	:	The mismatch read counts table  for individual isomiRs
isoform.filter.RPM.csv	:	The RPM table for individual isomiRs with noisy reads filtered out
isoform.RPM.csv	:	The RPM table for individual isomiRs
miR.Counts.csv	:	miRNA read counts table without filtering
miR.Counts.Mismatch.csv	:	miRNA mismatch read counts table without filtering
miR.RPM.csv	:	miRNA RPM table without filtering
miR.filter.Counts.csv	:	miRNA read counts table with filtering of noisy reads
miR.filter.Counts.Mismatch.csv	:	miRNA mismatch read counts table with filtering of noisy reads
miR.filter.RPM.csv	:	miRNA RPM table with filtering of noisy reads
miR.RPM.csv	:	miRNA RPM table without filtering
miRNASeq.readRedundancy.txt	:	Read redundancy in each annotated category
QAmiRSeq.summary.txt	:	The summary of read mapping and annotation
readAnnotDistribution.csv	:	The distribution of annotated reads
readLenDistribution.csv	:	The distribution of read lengths
smallRNA.Counts.csv :	smallRNA read counts table without filtering
uniqReads.library.csv	:	cumulative unique and total reads to be processed


Descriptions on summary plot
==========================================================================
cut-adapter-withAdapter.png	:	barplot--The percentage of reads with adapters
cut-adapter-TotalReads.png	:	barplot--sequence library size
cut-adapter-SurvivalReads.png	:	barplot--The percentage of survival reads after adapter trimming
joint-unique-mapping.png	:	the cumulative number of unique and total reads
miRNA-reads.png	:	barplot--total number of mapped miRNA reads in each sample
miRNA-reads-split.png	:	barplot--miRNA reads split between perfect and mismatch
miRNASeq-reads-annotation.png	:	barplot--distribution of annotated miRNA-seq reads
miRNA-detected.png	:	barplot--detected miRNAs with and without filtering
miRNA-counted.png	:	barplot--detected miRNAs after filtering
miR-rpm-corr.png	:	Expression correlation plot among all samples
miR-offset-5end.png	:	barplot--Distribution of 5-end offset of unique miRNA reads
miR-offset-3end.png		:	barplot--Distribution of 3-end offset of unique miRNA reads
miR-offset-53.png	:	3d-plot--Distribution of 5- and 3-end offset of unique miRNA reads
miRNASeq-reads-redundancy.png	:	barplot--redundancy of reads (#Reads/#Unique_Reads)
miRNASeq-reads-redundancy.scaleFree.png	:	barplot--same as miRNASeq-reads-redundancy.png but y scale-free
readRedundancy.hairpin.png	:	barplot--hairpin reads redundancy(#Reads/#Unique_Reads)
readRedundancy.miRNA_mismatch.png	:	barplot--miRNA reads (with mismatches) reads redundancy(#Reads/#Unique_Reads)
readRedundancy.miRNA.png	:	barplot--miRNA reads redundancy(#Reads/#Unique_Reads)
readRedundancy.mRNA.png	:	barplot--mRNA reads redundancy(#Reads/#Unique_Reads)
readRedundancy.smallRNA.png	:	barplot--smallRNA reads redundancy(#Reads/#Unique_Reads)
readRedundancy.Total.png	:	barplot--all reads redundancy(#Reads/#Unique_Reads)
readRedundancy.unaligned.png	:	barplot--unaligned reads redundancy(#Reads/#Unique_Reads)
total-miRNA-reads.png	:	barplot--total and miRNA reads in each sample
total-reads.png	:	barplot--total input reads in each sample for mapping