Provided by: rsem_1.2.31+dfsg-1_amd64 
NAME
rsem-prepare-reference
PURPOSE
Prepare transcript references for RSEM and optionally build BOWTIE/BOWTIE2/STAR indices.
SYNOPSIS
rsem-prepare-reference [options] reference_fasta_file(s) reference_name
ARGUMENTS
reference_fasta_file(s)
Either a comma-separated list of Multi-FASTA formatted files OR a directory name. If a directory name
is specified, RSEM will read all files with suffix ".fa" or ".fasta" in this directory. The files
should contain either the sequences of transcripts or an entire genome, depending on whether the
'--gtf' option is used.
reference name
The name of the reference used. RSEM will generate several reference-related files that are prefixed
by this name. This name can contain path information (e.g. '/ref/mm9').
OPTIONS
--gtf <file>
If this option is on, RSEM assumes that 'reference_fasta_file(s)' contains the sequence of a genome,
and will extract transcript reference sequences using the gene annotations specified in <file>, which
should be in GTF format.
If this and '--gff3' options are off, RSEM will assume 'reference_fasta_file(s)' contains the
reference transcripts. In this case, RSEM assumes that name of each sequence in the Multi-FASTA files
is its transcript_id.
(Default: off)
--gff3 <file>
The annotation file is in GFF3 format instead of GTF format. RSEM will first convert it to GTF format
with the file name 'reference_name.gtf'. Please make sure that 'reference_name.gtf' does not exist.
(Default: off)
--gff3-RNA-patterns <pattern>
<pattern> is a comma-separated list of transcript categories, e.g. "mRNA,rRNA". Only transcripts that
match the <pattern> will be extracted. (Default: "mRNA")
--trusted-sources <sources>
<sources> is a comma-separated list of trusted sources, e.g. "ENSEMBL,HAVANA". Only transcripts
coming from these sources will be extracted. If this option is off, all sources are accepted.
(Default: off)
--transcript-to-gene-map <file>
Use information from <file> to map from transcript (isoform) ids to gene ids. Each line of <file>
should be of the form:
gene_id transcript_id
with the two fields separated by a tab character.
If you are using a GTF file for the "UCSC Genes" gene set from the UCSC Genome Browser, then the
"knownIsoforms.txt" file (obtained from the "Downloads" section of the UCSC Genome Browser site) is
of this format.
If this option is off, then the mapping of isoforms to genes depends on whether the '--gtf' option is
specified. If '--gtf' is specified, then RSEM uses the "gene_id" and "transcript_id" attributes in
the GTF file. Otherwise, RSEM assumes that each sequence in the reference sequence files is a
separate gene.
(Default: off)
--allele-to-gene-map <file>
Use information from <file> to provide gene_id and transcript_id information for each allele-specific
transcript. Each line of <file> should be of the form:
gene_id transcript_id allele_id
with the fields separated by a tab character.
This option is designed for quantifying allele-specific expression. It is only valid if '--gtf'
option is not specified. allele_id should be the sequence names presented in the Multi-FASTA-
formatted files.
(Default: off)
--polyA
Add poly(A) tails to the end of all reference isoforms. The length of poly(A) tail added is specified
by '--polyA-length' option. STAR aligner users may not want to use this option. (Default: do not add
poly(A) tail to any of the isoforms)
--polyA-length <int>
The length of the poly(A) tails to be added. (Default: 125)
--no-polyA-subset <file>
Only meaningful if '--polyA' is specified. Do not add poly(A) tails to those transcripts listed in
<file>. <file> is a file containing a list of transcript_ids. (Default: off)
--bowtie
Build Bowtie indices. (Default: off)
--bowtie-path <path>
The path to the Bowtie executables. (Default: the path to Bowtie executables is assumed to be in the
user's PATH environment variable)
--bowtie2
Build Bowtie 2 indices. (Default: off)
--bowtie2-path
The path to the Bowtie 2 executables. (Default: the path to Bowtie 2 executables is assumed to be in
the user's PATH environment variable)
--star
Build STAR indices. (Default: off)
--star-path <path>
The path to STAR's executable. (Default: the path to STAR executable is assumed to be in user's PATH
environment varaible)
--star-sjdboverhang <int>
Length of the genomic sequence around annotated junction. It is only used for STAT to build splice
junctions database and not needed for Bowtie or Bowtie2. It will be passed as the --sjdbOverhang
option to STAR. According to STAR's manual, its ideal value is max(ReadLength)-1, e.g. for 2x101
paired-end reads, the ideal value is 101-1=100. In most cases, the default value of 100 will work as
well as the ideal value. (Default: 100)
-p/--num-threads <int>
Number of threads to use for building STAR's genome indices. (Default: 1)
-q/--quiet
Suppress the output of logging information. (Default: off)
-h/--help
Show help information.
DESCRIPTION
This program extracts/preprocesses the reference sequences for RSEM. It can optionally build Bowtie
indices (with '--bowtie' option) and/or Bowtie 2 indices (with '--bowtie2' option) using their default
parameters. It can also optionally build STAR indices (with '--star' option) using parameters from
ENCODE3's STAR-RSEM pipeline. If an alternative aligner is to be used, indices for that particular
aligner can be built from either 'reference_name.idx.fa' or 'reference_name.n2g.idx.fa' (see OUTPUT for
details). This program is used in conjunction with the 'rsem-calculate-expression' program.
OUTPUT
This program will generate 'reference_name.grp', 'reference_name.ti', 'reference_name.transcripts.fa',
'reference_name.seq', 'reference_name.chrlist' (if '--gtf' is on), 'reference_name.idx.fa',
'reference_name.n2g.idx.fa', optional Bowtie/Bowtie 2 index files, and optional STAR index files.
'reference_name.grp', 'reference_name.ti', 'reference_name.seq', and 'reference_name.chrlist' are used by
RSEM internally.
'reference_name.transcripts.fa' contains the extracted reference transcripts in Multi-FASTA format.
Poly(A) tails are not added and it may contain lower case bases in its sequences if the corresponding
genomic regions are soft-masked.
'reference_name.idx.fa' and 'reference_name.n2g.idx.fa' are used by aligners to build their own indices.
In these two files, all sequence bases are converted into upper case. In addition, poly(A) tails are
added if '--polyA' option is set. The only difference between 'reference_name.idx.fa' and
'reference_name.n2g.idx.fa' is that 'reference_name.n2g.idx.fa' in addition converts all 'N' characters
to 'G' characters. This conversion is in particular desired for aligners (e.g. Bowtie) that do not allow
reads to overlap with 'N' characters in the reference sequences. Otherwise, 'reference_name.idx.fa'
should be used to build the aligner's index files. RSEM uses 'reference_name.idx.fa' to build Bowtie 2
indices and 'reference_name.n2g.idx.fa' to build Bowtie indices. For visualizing the transcript-
coordinate-based BAM files generated by RSEM in IGV, 'reference_name.idx.fa' should be imported as a
"genome" (see Visualization section in README.md for details).
EXAMPLES
1) Suppose we have mouse RNA-Seq data and want to use the UCSC mm9 version of the mouse genome. We have
downloaded the UCSC Genes transcript annotations in GTF format (as mm9.gtf) using the Table Browser and
the knownIsoforms.txt file for mm9 from the UCSC Downloads. We also have all chromosome files for mm9 in
the directory '/data/mm9'. We want to put the generated reference files under '/ref' with name
'mouse_0'. We do not add any poly(A) tails. Please note that GTF files generated from UCSC's Table
Browser do not contain isoform-gene relationship information. For the UCSC Genes annotation, this
information can be obtained from the knownIsoforms.txt file. Suppose we want to build Bowtie indices and
Bowtie executables are found in '/sw/bowtie'.
There are two ways to write the command:
rsem-prepare-reference --gtf mm9.gtf \
--transcript-to-gene-map knownIsoforms.txt \
--bowtie \
--bowtie-path /sw/bowtie \
/data/mm9/chr1.fa,/data/mm9/chr2.fa,...,/data/mm9/chrM.fa \
/ref/mouse_0
OR
rsem-prepare-reference --gtf mm9.gtf \
--transcript-to-gene-map knownIsoforms.txt \
--bowtie \
--bowtie-path /sw/bowtie \
/data/mm9 \
/ref/mouse_0
2) Suppose we also want to build Bowtie 2 indices in the above example and Bowtie 2 executables are found
in '/sw/bowtie2', the command will be:
rsem-prepare-reference --gtf mm9.gtf \
--transcript-to-gene-map knownIsoforms.txt \
--bowtie \
--bowtie-path /sw/bowtie \
--bowtie2 \
--bowtie2-path /sw/bowtie2 \
/data/mm9 \
/ref/mouse_0
3) Suppose we want to build STAR indices in the above example and save index files under '/ref' with name
'mouse_0'. Assuming STAR executable is '/sw/STAR', the command will be:
rsem-prepare-reference --gtf mm9.gtf \
--star \
--star-path /sw/STAR \
-p 8 \
/data/mm9/chr1.fa,/data/mm9/chr2.fa,...,/data/mm9/chrM.fa \
/ref/mouse_0
OR
rsem-prepare-reference --gtf mm9.gtf \
--star \
--star-path /sw/STAR \
-p 8 \
/data/mm9
/ref/mouse_0
STAR genome index files will be saved under '/ref/'.
4) Suppose we only have transcripts from EST tags stored in 'mm9.fasta' and isoform-gene information
stored in 'mapping.txt'. We want to add 125bp long poly(A) tails to all transcripts. The reference_name
is set as 'mouse_125'. In addition, we do not want to build Bowtie/Bowtie 2 indices, and will use an
alternative aligner to align reads against either 'mouse_125.idx.fa' or 'mouse_125.idx.n2g.fa':
rsem-prepare-reference --transcript-to-gene-map mapping.txt \
--polyA
mm9.fasta \
mouse_125
perl v5.22.2 2016-06-04 RSEM-PREPARE-REFERENCE(1)