* [Simulation](#simulation)
* [Generate Transcript-to-Gene-Map from Trinity Output](#gen_trinity)
* [Differential Expression Analysis](#de)
+* [Authors](#authors)
* [Acknowledgements](#acknowledgements)
* [License](#license)
### Prerequisites
-C++ and Perl are required to be installed.
+C++, Perl and R are required to be installed.
To take advantage of RSEM's built-in support for the Bowtie alignment
program, you must have [Bowtie](http://bowtie-bio.sourceforge.net) installed.
-If you want to plot model learned by RSEM, you should also install R.
-
## <a name="usage"></a> Usage
### I. Preparing Reference Sequences
generated by the samtools included. All these files are in genomic
coordinates.
-#### a) Generating a Wiggle file
+#### a) Converting transcript BAM file into genome BAM file
+
+Normally, RSEM will do this for you via '--output-genome-bam' option
+of 'rsem-calculate-expression'. However, if you have run
+'rsem-prepare-reference' and use 'reference_name.idx.fa' to build
+indices for your aligner, you can use 'rsem-tbam2gbam' to convert your
+transcript coordinate BAM alignments file into a genomic coordinate
+BAM alignments file without the need to run the whole RSEM
+pipeline. Please note that 'rsem-prepare-reference' will convert all
+'N' into 'G' by default for 'reference_name.idx.fa'. If you do not
+want this to happen, please use '--no-ntog' option.
+
+Usage:
+
+ rsem-tbam2gbam reference_name unsorted_transcript_bam_input genome_bam_output
+
+reference_name : The name of reference built by 'rsem-prepare-reference'
+unsorted_transcript_bam_input : This file should satisfy: 1) the alignments of a same read are grouped together, 2) for any paired-end alignment, the two mates should be adjacent to each other, 3) this file should not be sorted by samtools
+genome_bam_output : The output genomic coordinate BAM file's name
+
+#### b) Generating a Wiggle file
A wiggle plot representing the expected number of reads overlapping
each position in the genome/transcript set can be generated from the
Usage:
- rsem-bam2wig sorted_bam_input wig_output wiggle_name
+ rsem-bam2wig sorted_bam_input wig_output wiggle_name [--no-fractional-weight]
-sorted_bam_input: sorted bam file
-wig_output: output file name, e.g. output.wig
-wiggle_name: the name the user wants to use for this wiggle plot
+sorted_bam_input : Input BAM format file, must be sorted
+wig_output : Output wiggle file's name, e.g. output.wig
+wiggle_name : the name of this wiggle plot
+--no-fractional-weight : If this is set, RSEM will not look for "ZW" tag and each alignment appeared in the BAM file has weight 1. Set this if your BAM file is not generated by RSEM. Please note that this option must be at the end of the command line
-#### b) Loading a BAM and/or Wiggle file into the UCSC Genome Browser or Integrative Genomics Viewer(IGV)
+#### c) Loading a BAM and/or Wiggle file into the UCSC Genome Browser or Integrative Genomics Viewer(IGV)
For UCSC genome browser, please refer to the [UCSC custom track help page](http://genome.ucsc.edu/goldenPath/help/customTrack.html).
igvtools tile reference_name.transcript.wig reference_name.transcript.tdf reference_name.genome
-#### c) Generating Transcript Wiggle Plots
+#### d) Generating Transcript Wiggle Plots
To generate transcript wiggle plots, you should run the
'rsem-plot-transcript-wiggles' program. Run
to get usage information or visit the [rsem-plot-transcript-wiggles
documentation page](http://deweylab.biostat.wisc.edu/rsem/rsem-plot-transcript-wiggles.html).
-#### d) Visualize the model learned by RSEM
+#### e) Visualize the model learned by RSEM
RSEM provides an R script, 'rsem-plot-model', for visulazing the model learned.
DESeq do not take variance due to read mapping uncertainty into
consideration. Because read mapping ambiguity is prevalent among
isoforms and de novo assembled transcripts, these tools are not ideal
-for DE detection in such conditions.
+for DE detection in such conditions.
+
+EBSeq, an empirical Bayesian DE analysis tool developed in UW-Madison,
+can take variance due to read mapping ambiguity into consideration by
+grouping isoforms with parent gene's number of isoforms. In addition,
+it is more robust to outliers. For more information about EBSeq
+(including the paper describing their method), please visit [EBSeq's
+website](http://www.biostat.wisc.edu/~ningleng/EBSeq_Package).
+
-**EBSeq**, an empirical Bayesian DE
-analysis tool developed in UW-Madison, can take variance due to read
-mapping ambiguity into consideration by grouping isoforms with parent
-gene's number of isoforms. In addition, it is more robust to
-outliers. RSEM includes the newest version of EBSeq in the folder
-named 'EBSeq'.
+RSEM includes EBSeq in its folder named 'EBSeq'. To use it, first type
-For more information about EBSeq (including the paper describing their
-method), please visit <a
-href="http://www.biostat.wisc.edu/~ningleng/EBSeq_Package">EBSeq
-website</a>. You can also find a local version of vignette under
-'EBSeq/inst/doc/EBSeq_Vignette.pdf'.
+ make ebseq
+
+to compile the EBSeq related codes.
EBSeq requires gene-isoform relationship for its isoform DE
detection. However, for de novo assembled transcriptome, it is hard to
obtain an accurate gene-isoform relationship. Instead, RSEM provides a
-script 'rsem-generate-ngvector', which clusters isoforms based on
+script 'rsem-generate-ngvector', which clusters transcripts based on
measures directly relating to read mappaing ambiguity. First, it
calcualtes the 'unmappability' of each transcript. The 'unmappability'
of a transcript is the ratio between the number of k mers with at
NgVec <- scan(file="output_name.ngvec", what=0, sep="\n")
-. After that, replace 'IsoNgTrun' with 'NgVec' in the second line of
-section 3.2.5 (Page 10) of EBSeq's vignette:
+. After that, set "NgVector = NgVec" for your differential expression
+test (either 'EBTest' or 'EBMultiTest').
- IsoEBres=EBTest(Data=IsoMat, NgVector=NgVec, ...)
For users' convenience, RSEM also provides a script
-'rsem-form-counts-matrix' to extract input matrix from expression
+'rsem-generate-data-matrix' to extract input matrix from expression
results:
- rsem-form-counts-matrix sampleA.[genes/isoforms].results sampleB.[genes/isoforms].results ... > output_name.counts.matrix
+ rsem-generate-data-matrix sampleA.[genes/isoforms].results sampleB.[genes/isoforms].results ... > output_name.counts.matrix
The results files are required to be either all gene level results or
all isoform level results. You can load the matrix into R by
- IsoMat <- read.table(file="output_name.counts.matrix")
+ IsoMat <- data.matrix(read.table(file="output_name.counts.matrix"))
-before running function 'EBTest'.
+before running either 'EBTest' or 'EBMultiTest'.
+
+Lastly, RSEM provides two scripts, 'rsem-run-ebseq' and
+'rsem-control-fdr', to help users find differential expressed
+genes/transcripts. First, 'rsem-run-ebseq' calls EBSeq to calculate related statistics
+for all genes/transcripts. Run
+
+ rsem-run-ebseq --help
+
+to get usage information or visit the [rsem-run-ebseq documentation
+page](http://deweylab.biostat.wisc.edu/rsem/rsem-run-ebseq.html). Second,
+'rsem-control-fdr' takes 'rsem-run-ebseq' 's result and reports called
+differentially expressed genes/transcripts by controlling the false
+discovery rate. Run
+
+ rsem-control-fdr --help
+
+to get usage information or visit the [rsem-control-fdr documentation
+page](http://deweylab.biostat.wisc.edu/rsem/rsem-control-fdr.html). These
+two scripts can perform DE analysis on either 2 conditions or multiple
+conditions.
+
+Please note that 'rsem-run-ebseq' and 'rsem-control-fdr' use EBSeq's
+default parameters. For advanced use of EBSeq or information about how
+EBSeq works, please refer to [EBSeq's
+manual](http://www.bioconductor.org/packages/devel/bioc/vignettes/EBSeq/inst/doc/EBSeq_Vignette.pdf).
+
+Questions related to EBSeq should
+be sent to <a href="mailto:nleng@wisc.edu">Ning Leng</a>.
+
+## <a name="authors"></a> Authors
+
+RSEM is developed by Bo Li, with substaintial technical input from Colin Dewey.
-Questions related to EBSeq should be sent to <a href="mailto:nleng@wisc.edu">Ning Leng</a>.
-
## <a name="acknowledgements"></a> Acknowledgements
RSEM uses the [Boost C++](http://www.boost.org) and
We thank earonesty for contributing patches.
+We thank Han Lin for suggesting possible fixes.
+
## <a name="license"></a> License
RSEM is licensed under the [GNU General Public License