PIPmiR v1.1
*******************************************
Requirements:

Required:
4G RAM (for classifier or pipeline)
JAVA version '1.6.0'
RNAfold (http://www.tbi.univie.ac.at/RNA/)
UCSC .2bit version of the genome against which the reads were aligned (http://genome.ucsc.edu/FAQ/FAQformat.html#/format7)
samtools for the pipeline and classifier [not needed for precursor prediction] (http://samtools.sourceforge.net/)
sorted .BAM alignment file (http://samtools.sourceforge.net/samtools.shtml)
sorted .BAM index file (.bai)

Recommended:
8G RAM
bowtie (earlier than version 2) (http://bowtie-bio.sourceforge.net/index.shtml)
As many cores as possible (precursor prediction is a slow, but luckily threadable, process)
*******************************************
Usage:
>PIPmiR <command> [options]

	<command> is either PIPELINE, PRECURSOR, TRAIN, or CLASSIFIER
*******************************************


*******************************************
Command: 'PIPELINE'
This option will run the entire pipeline, meaning that it will identify putative mature miRNAs
from an alignment file, determine which of those have valid precursors, and then run the classifier
to determine if they could be novel miRNAs

Required parameters:
-a <alignment_file.bam>
	<alignment_file.bam> needs to be a sorted .bam file; you will also need an index file that has 
	the same basename as your file, but with the .bai extension
	Reccomended Commands to generate this:
		>bowtie <bowtieIndex> -f my_sequence_file.FASTA -S -m 25 --all --best --strata > my_alignment_results.sam
		>samtools view -b my_alignment_results.sam > my_alignment_results.bam
		>samtools sort my_alignment_results.bam my_alignment_results_sorted
		>samtools index my_alignment_results_sorted.bam my_alignment_results_sorted
		You will now have 2 files: 
			my_alignment_results_sorted.bam; this is what will be needed for PIPmiR in this -a option
			my_alignment_results_sorted.bai; this is read by PIPmiR, and needs to be in the same folder as the given my_alignment_results_sorted.bam
-t <genome_file.2bit>
	<genome_file.2bit> needs to be a .2bit version of the genome that you aligned your reads against
		see (http://genome.ucsc.edu/FAQ/FAQformat.html#/format7) for more information
-o <output_header>
	<output_header> will be the basename for the output files
		3 files will be generated (4 if you create a log file, see optional parameters below)
			<output_header>_putativeMatures.bed
				This will be a .bed file (http://genome.ucsc.edu/FAQ/FAQformat.html#format1)
				The 'score' column will be the read count and the name column will be an arbitrary name given to the putative mature
			<output_header>_predictedPrecursors.txt
				This will be a file that contains the predictured precursors for the putative matures (if there was one)
				I have created a special section about this file type below, see "PUTATIVE PRECURSOR FILE Description"
			<output_header>_predicted_miRNAs.txt
				This file will contain the miRNAs that had a positive classifier score, meaning that PIPmiR believes that they may be novel miRNA genes
				This file contains the genomic coordinates of the predicted precursor as well as for the mature and star sequences
				The file also contains the precursor sequence and foldback structure

Optional parameters:
-l <size>
	<size> is the MINIMUM size that the precursor predictor can begin searching, 50 is reccomended (and is the default)
-L <size>
	<size> is the MAXIMUM size that the precursor predictor can search
		The larger you make this, the longer PIPmiR will take as folding time is exponential with increased size
		500 is what was used in the manuscript and will include almost all currently known arabidopsis thaliana miRNAs
		300 is a limit that will include most known miRNAs and still have a reasonable search time
-s <step_size>
	<step_size> is the step size used to identifiy the precursor from the minimum (-l) to the maximum (-L) possible length
		Increasing this value will speed up the precursor prediction step but limit the number of possible precursor sequences
		2 is the default and is what was used in the manuscript, however 5 still works well enough, and is only slightly less accurate
-m <read_count>
	<read_count> is the minumum number of reads necessary at a location for it to be considered a putative miRNA
	The default is 10, however if you are using the HiSeq, you may be able to increase this
-p <number_of_threads>
	<number_of_threads> is the maximum number of threads the PIPmiR can use 
	Hopefully you can increase this from the default of 1
-X <max_memory_allowed>
	<maximum_memory_allowed> is the largest amount of memory you allow PIPmiR to run in
	PIPmiR isn't overly memory intensive, as 4G is likely enough for most libraries
-R <RNAfold_location>
	<RNAfold_location> = location of RNAfold executable
-d
	Creates a log file of PIPmiR results at <output_header>_log.csv
	The file will contain the putative miRNA name, if it passed the precursor predictor, and what it's classification values were
	If it failed the precursor predictor, it will tell you why:
		Failed(Step1): no valid star sequence was identified from minimum precursor size (-l) to the maximum size allowed (-L)
		Failed(Trimming): after trimming the stem to just the miRNA-miRNA*, refolding resulted in a non-valid miRNA*
		Failed(Step2): no valid star sequence was identified after extending the miRNA-miRNA* hairpin structure
		Failed(StarDidNotMatch): the miRNA* identified after Step1 was no the same miRNA* identified after extending the miRNA-miRNA* hairpin structure
								 to the lowest normalized free energy / length value
								 **This will be the most common
-T <training_file>
        Name of the training data file, must be placed in the ./src/ directory
	The default is ./src/TrainingData.dat
*******************************************


*******************************************
Command: 'PRECURSOR'
This option will attempt to identify the precursor structure for putative mature miRNAs.  This option will take in coordinates of possible miRNAs (in bed format)
and generate the putative precursor sequence & foldback.  No classification will be done on these possible miRNAs, and therefore no alignment file is necessary.  
This option can be used if you already have poptential miRNAs and want to identify what their likely precursor sequence & structure could be.

Required parameters:
-b <mature_file.bed>
	<mature_file.bed> is a .bed (http://genome.ucsc.edu/FAQ/FAQformat.html#format1) file containing the putative mature miRNA coordinates
		The score column can be any arbitrary value, but needs to be there for proper processing
-t <genome_file.2bit>
	<genome_file.2bit> needs to be a .2bit version of the genome that you aligned your reads against
		see (http://genome.ucsc.edu/FAQ/FAQformat.html#/format7) for more information
-o <output_header>
	<output_header> will be the basename for the output files
		1 file will be generated (2 if you create a log file, see optional parameters below)
			<output_header>_predictedPrecursors.txt
				This will be a file that contains the predictured precursors for the putative matures (if there was one)
				I have created a special section about this file type below, see "PUTATIVE PRECURSOR FILE Description"

Optional parameters:
-l <size>
	<size> is the MINIMUM size that the precursor predictor can begin searching, 50 is reccomended (and is the default)
-L <size>
	<size> is the MAXIMUM size that the precursor predictor can search
		The larger you make this, the longer PIPmiR will take as folding time is exponential with increased size
		500 is what was used in the manuscript and will include almost all currently known arabidopsis thaliana miRNAs
		300 is a limit that will include most known miRNAs and still have a reasonable search time
-s <step_size>
	<step_size> is the step size used to identifiy the precursor from the minimum (-l) to the maximum (-L) possible length
		Increasing this value will speed up the precursor prediction step but limit the number of possible precursor sequences
		2 is the default and is what was used in the manuscript, however 5 still works well enough, and is only slightly less accurate
-p <number_of_threads>
	<number_of_threads> is the maximum number of threads the PIPmiR can use 
	Hopefully you can increase this from the default of 1
-X <max_memory_allowed>
	<maximum_memory_allowed> is the largest amount of memory you allow PIPmiR to run in
	The precursor predictor isn't memory intensive at all, as 1G is likely enough for most libraries
-R <RNAfold_location>
	<RNAfold_location> = location of RNAfold executable
-d
	Creates a log file of PIPmiR results at <output_header>_log.csv
	The file will contain the putative miRNA name, if it passed the precursor predictor, and what it's classification values were.
	The classification values will be 'NA' since no classification is being done using this command option
	If it failed the precursor predictor, it will tell you why:
		Failed(Step1): no valid star sequence was identified from minimum precursor size (-l) to the maximum size allowed (-L)
		Failed(Trimming): after trimming the stem to just the miRNA-miRNA*, refolding resulted in a non-valid miRNA*
		Failed(Step2): no valid star sequence was identified after extending the miRNA-miRNA* hairpin structure
		Failed(StarDidNotMatch): the miRNA* identified after Step1 was no the same miRNA* identified after extending the miRNA-miRNA* hairpin structure
								 to the lowest normalized free energy / length value
								 **This will be the most common
*******************************************

*******************************************
Command: 'TRAIN'
This command will allow you to generate your own training data.  It requires you to have two precursor files, one of positive examples,
and the other for negative examples.  It also requires that you have an alignment file (.bam).  Please keep in mind that you will want
an approximate ratio of negative:positive of 2,250:1 to maintian consistent priors

Required parameters:
-P <precursor_file>
                This is a file that contains the predictured precursors for **NEGATIVE EXAMPLE** miRNAs
                I have created a special section about this file type below, see "PUTATIVE PRECURSOR FILE Description"
                It is the same as what is generated by the precursor prediction algorithm used in either the 'PIPELINE' or 'PRECURSOR' commands
-K <precursor_file>
                This is a file that contains the predictured precursors for **POSITIVE EXAMPLE** miRNAs
                I have created a special section about this file type below, see "PUTATIVE PRECURSOR FILE Description"
                It is the same as what is generated by the precursor prediction algorithm used in either the 'PIPELINE' or 'PRECURSOR' commands
-a <alignment_file.bam>
        <alignment_file.bam> needs to be a sorted .bam file; you will also need an index file that has
        the same basename as your file, but with the .bai extension
        Reccomended Commands to generate this:
                >bowtie <bowtieIndex> -f my_sequence_file.FASTA -S -m 25 --all --best --strata > my_alignment_results.sam
                >samtools view -b my_alignment_results.sam > my_alignment_results.bam
                >samtools sort my_alignment_results.bam my_alignment_results_sorted
                >samtools index my_alignment_results_sorted.bam my_alignment_results_sorted
                You will now have 2 files:
                        my_alignment_results_sorted.bam; this is what will be needed for PIPmiR in this -a option
                        my_alignment_results_sorted.bai; this is read by PIPmiR, and needs to be in the same folder as the given my_alignment_results_sorted.bam
-T <output_training_file>
		This will be the output file containing your new training data

Optional parameters:
-m <read_count>
        <read_count> is the minumum number of reads necessary at a location for it to be considered a putative miRNA
        The default is 10, however if you are using the HiSeq, you may be able to increase this
-X <max_memory_allowed>
        <maximum_memory_allowed> is the largest amount of memory you allow PIPmiR to run in
        PIPmiR isn't overly memory intensive, as 4G is likely enough for most libraries
*******************************************

*******************************************
Command: 'CLASSIFIER'
This command will run the classification method only.  It requires you to have an alignment file as well as a precursor file.  It will identify
putative miRNAs using the naive-Bayes classifier.

Required parameters:
-P <precursor_file>
		This is a file that contains the predictured precursors for putative mature miRNAs
		I have created a special section about this file type below, see "PUTATIVE PRECURSOR FILE Description"
		It is the same as what is generated by the precursor prediction algorithm used in either the 'PIPELINE' or 'PRECURSOR' commands
-a <alignment_file.bam>
	<alignment_file.bam> needs to be a sorted .bam file; you will also need an index file that has 
	the same basename as your file, but with the .bai extension
	Reccomended Commands to generate this:
		>bowtie <bowtieIndex> -f my_sequence_file.FASTA -S -m 25 --all --best --strata > my_alignment_results.sam
		>samtools view -b my_alignment_results.sam > my_alignment_results.bam
		>samtools sort my_alignment_results.bam my_alignment_results_sorted
		>samtools index my_alignment_results_sorted.bam my_alignment_results_sorted
		You will now have 2 files: 
			my_alignment_results_sorted.bam; this is what will be needed for PIPmiR in this -a option
			my_alignment_results_sorted.bai; this is read by PIPmiR, and needs to be in the same folder as the given my_alignment_results_sorted.bam
-o <output_header>
	<output_header> will be the basename for the output files
		1 files will be generated (2 if you create a log file, see optional parameters below)
			<output_header>_predicted_miRNAs.txt
				This file will contain the miRNAs that had a positive classifier score, meaning that PIPmiR believes that they may be novel miRNA genes
				This file contains the genomic coordinates of the predicted precursor as well as for the mature and star sequences
				The file also contains the precursor sequence and foldback structure

Optional parameters:
-m <read_count>
	<read_count> is the minumum number of reads necessary at a location for it to be considered a putative miRNA
	The default is 10, however if you are using the HiSeq, you may be able to increase this
-X <max_memory_allowed>
	<maximum_memory_allowed> is the largest amount of memory you allow PIPmiR to run in
	PIPmiR isn't overly memory intensive, as 4G is likely enough for most libraries
-d
	Creates a log file of PIPmiR results at <output_header>_log.csv
	The file will contain the putative miRNA name, if it passed the precursor predictor, and what it's classification values were
	If it failed the precursor predictor, it will tell you why:
		Failed(NoValidStar): there is not a valid star in the given precursor structure for the mature
-T <training_file>
	Name of the training data file, must be placed in the ./src/ directory
        The default is ./src/TrainingData.dat
*******************************************

*******************************************
PUTATIVE PRECURSOR FILE Description

This is a comma-separated file that contains the information about a precursor & the mature within that precursor:
It is of the form:
Chromosome,Strand,Precursor_Start,Precursor_End,Sequence,Fold_Structure,Normalized_Minimum_Free_Energy,Mature_miRNA_Location
Chromosome = chromosome that the precursor is on
Strand = strand that the precursor is on
Precursor_Start = start nucleotide (1 based) of the precursor
Precursor_End = last nucleotide (1 based, inclusive) of the precursor
Sequence = sequence of the precursor
Fold_Structure = dot-bracket notation of the precursor fold centroid secondary structure (generated from RNAfold -p -d2 -noLP -noPS)
Normalized_Minimum_Free_Energy = Minimum free enrgy of the centroid structure divided by the length of the sequence
Mature_miRNA_location = name & location of the mature miRNA within the precursor sequence
		(<mature_miRNA_name>;<start_position>;<end_position>)
			<mature_miRNA_name>: name of the mature
			<start_position>: location of the start of the mature miRNA from the 5' end of the precursor (indexed at 0)
			<end_position>: location of the last nucleotide of the mature miRNA from the 5' end of the precursor (indexed at 0, inclusive)
*******************************************

*******************************************
**Note: I used the PICARD (http://picard.sourceforge.net/) libraries in this toolkit.
This is the license for these libraries:
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*******************************************
