QuickMIRSeq Files

#
#   QuickMIRSeq: 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 QuickMIRSeq using
#    setenv QuickMIRSeq QuickMIRSeq_installation_Directory
#  Not  set QuickMIRSeq QuickMIRSeq_installation_Directory
#!!!	

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

#set environment variable to point to your installation directory
export QuickMIRSeq=QuickMIRSeq_installation_Directory

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


#
## Step #1: Preparation of miRNA/hairpin/mRNA/smallRNA database
#
After you download and unpack the QuickMIRSeq package, you should 
	1. go to $QuickMIRSeq/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 $QuickMIRSeq/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

Optionally, you can create sample.annotation.txt file for meta data and put it under
the output folder (specified in run.config). Please refer to #Step #3 for details on format.

There is run.config.template that comes with QuickMIRSeq package. You can copy this template
and then customize it.

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


#
#Step #3: Generate an integrated report
#

Go to your output folder, and run a single command line
	$QuickMIRSeq/QuickMIRSeq-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.
 QuickMIRSeq 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 QuickMIRSeq.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
QuickMIRSeq.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