.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "RSEM-PREPARE-REFERENCE 1" .TH RSEM-PREPARE-REFERENCE 1 "2018-02-18" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" rsem\-prepare\-reference .SH "PURPOSE" .IX Header "PURPOSE" Prepare transcript references for \s-1RSEM\s0 and optionally build \s-1BOWTIE/BOWTIE2/STAR\s0 indices. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& rsem\-prepare\-reference [options] reference_fasta_file(s) reference_name .Ve .SH "ARGUMENTS" .IX Header "ARGUMENTS" .IP "\fBreference_fasta_file(s)\fR" 4 .IX Item "reference_fasta_file(s)" Either a comma-separated list of Multi-FASTA formatted files \s-1OR\s0 a directory name. If a directory name is specified, \s-1RSEM\s0 will read all files with suffix \*(L".fa\*(R" or \*(L".fasta\*(R" in this directory. The files should contain either the sequences of transcripts or an entire genome, depending on whether the '\-\-gtf' option is used. .IP "\fBreference name\fR" 4 .IX Item "reference name" The name of the reference used. \s-1RSEM\s0 will generate several reference-related files that are prefixed by this name. This name can contain path information (e.g. '/ref/mm9'). .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-\-gtf\fR " 4 .IX Item "--gtf " If this option is on, \s-1RSEM\s0 assumes that 'reference_fasta_file(s)' contains the sequence of a genome, and will extract transcript reference sequences using the gene annotations specified in , which should be in \s-1GTF\s0 format. .Sp If this and '\-\-gff3' options are off, \s-1RSEM\s0 will assume 'reference_fasta_file(s)' contains the reference transcripts. In this case, \s-1RSEM\s0 assumes that name of each sequence in the Multi-FASTA files is its transcript_id. .Sp (Default: off) .IP "\fB\-\-gff3\fR " 4 .IX Item "--gff3 " The annotation file is in \s-1GFF3\s0 format instead of \s-1GTF\s0 format. \s-1RSEM\s0 will first convert it to \s-1GTF\s0 format with the file name 'reference_name.gtf'. Please make sure that 'reference_name.gtf' does not exist. (Default: off) .IP "\fB\-\-gff3\-RNA\-patterns\fR " 4 .IX Item "--gff3-RNA-patterns " is a comma-separated list of transcript categories, e.g. \*(L"mRNA,rRNA\*(R". Only transcripts that match the will be extracted. (Default: \*(L"mRNA\*(R") .IP "\fB\-\-trusted\-sources\fR " 4 .IX Item "--trusted-sources " is a comma-separated list of trusted sources, e.g. \*(L"\s-1ENSEMBL,HAVANA\*(R".\s0 Only transcripts coming from these sources will be extracted. If this option is off, all sources are accepted. (Default: off) .IP "\fB\-\-transcript\-to\-gene\-map\fR " 4 .IX Item "--transcript-to-gene-map " Use information from to map from transcript (isoform) ids to gene ids. Each line of should be of the form: .Sp gene_id transcript_id .Sp with the two fields separated by a tab character. .Sp If you are using a \s-1GTF\s0 file for the \*(L"\s-1UCSC\s0 Genes\*(R" gene set from the \s-1UCSC\s0 Genome Browser, then the \*(L"knownIsoforms.txt\*(R" file (obtained from the \*(L"Downloads\*(R" section of the \s-1UCSC\s0 Genome Browser site) is of this format. .Sp 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 \s-1RSEM\s0 uses the \*(L"gene_id\*(R" and \*(L"transcript_id\*(R" attributes in the \s-1GTF\s0 file. Otherwise, \s-1RSEM\s0 assumes that each sequence in the reference sequence files is a separate gene. .Sp (Default: off) .IP "\fB\-\-allele\-to\-gene\-map\fR " 4 .IX Item "--allele-to-gene-map " Use information from to provide gene_id and transcript_id information for each allele-specific transcript. Each line of should be of the form: .Sp gene_id transcript_id allele_id .Sp with the fields separated by a tab character. .Sp 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. .Sp (Default: off) .IP "\fB\-\-polyA\fR" 4 .IX Item "--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. \s-1STAR\s0 aligner users may not want to use this option. (Default: do not add poly(A) tail to any of the isoforms) .IP "\fB\-\-polyA\-length\fR " 4 .IX Item "--polyA-length " The length of the poly(A) tails to be added. (Default: 125) .IP "\fB\-\-no\-polyA\-subset\fR " 4 .IX Item "--no-polyA-subset " Only meaningful if '\-\-polyA' is specified. Do not add poly(A) tails to those transcripts listed in . is a file containing a list of transcript_ids. (Default: off) .IP "\fB\-\-bowtie\fR" 4 .IX Item "--bowtie" Build Bowtie indices. (Default: off) .IP "\fB\-\-bowtie\-path\fR " 4 .IX Item "--bowtie-path " The path to the Bowtie executables. (Default: the path to Bowtie executables is assumed to be in the user's \s-1PATH\s0 environment variable) .IP "\fB\-\-bowtie2\fR" 4 .IX Item "--bowtie2" Build Bowtie 2 indices. (Default: off) .IP "\fB\-\-bowtie2\-path\fR" 4 .IX Item "--bowtie2-path" The path to the Bowtie 2 executables. (Default: the path to Bowtie 2 executables is assumed to be in the user's \s-1PATH\s0 environment variable) .IP "\fB\-\-star\fR" 4 .IX Item "--star" Build \s-1STAR\s0 indices. (Default: off) .IP "\fB\-\-star\-path\fR " 4 .IX Item "--star-path " The path to \s-1STAR\s0's executable. (Default: the path to \s-1STAR\s0 executable is assumed to be in user's \s-1PATH\s0 environment varaible) .IP "\fB\-\-star\-sjdboverhang\fR " 4 .IX Item "--star-sjdboverhang " Length of the genomic sequence around annotated junction. It is only used for \s-1STAT\s0 to build splice junctions database and not needed for Bowtie or Bowtie2. It will be passed as the \-\-sjdbOverhang option to \s-1STAR.\s0 According to \s-1STAR\s0'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) .IP "\fB\-p/\-\-num\-threads\fR " 4 .IX Item "-p/--num-threads " Number of threads to use for building \s-1STAR\s0's genome indices. (Default: 1) .IP "\fB\-q/\-\-quiet\fR" 4 .IX Item "-q/--quiet" Suppress the output of logging information. (Default: off) .IP "\fB\-h/\-\-help\fR" 4 .IX Item "-h/--help" Show help information. .SH "PRIOR-ENHANCED RSEM OPTIONS" .IX Header "PRIOR-ENHANCED RSEM OPTIONS" .IP "\fB\-\-prep\-pRSEM\fR" 4 .IX Item "--prep-pRSEM" A Boolean indicating whether to prepare reference files for pRSEM, including building Bowtie indices for a genome and selecting training set isoforms. The index files will be used for aligning ChIP-seq reads in prior-enhanced \s-1RSEM\s0 and the training set isoforms will be used for learning prior. A path to Bowtie executables and a mappability file in bigWig format are required when this option is on. Currently, Bowtie2 is not supported for prior-enhanced \s-1RSEM.\s0 (Default: off) .IP "\fB\-\-mappability\-bigwig\-file\fR " 4 .IX Item "--mappability-bigwig-file " Full path to a whole-genome mappability file in bigWig format. This file is required for running prior-enhanced \s-1RSEM.\s0 It is used for selecting a training set of isoforms for prior-learning. This file can be either downloaded from \s-1UCSC\s0 Genome Browser or generated by \s-1GEM\s0 (Derrien et al., 2012, PLoS One). (Default: "") .SH "DESCRIPTION" .IX Header "DESCRIPTION" This program extracts/preprocesses the reference sequences for \s-1RSEM\s0 and prior-enhanced \s-1RSEM.\s0 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 \s-1STAR\s0 indices (with '\-\-star' option) using parameters from \s-1ENCODE3\s0's STAR-RSEM pipeline. For prior-enhanced \s-1RSEM,\s0 it can build Bowtie genomic indices and select training set isoforms (with options '\-\-prep\-pRSEM' and '\-\-mappability\-bigwig\-file '). 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 \s-1OUTPUT\s0 for details). This program is used in conjunction with the 'rsem\-calculate\-expression' program. .SH "OUTPUT" .IX Header "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 \s-1STAR\s0 index files. .PP \&'reference_name.grp', 'reference_name.ti', 'reference_name.seq', and 'reference_name.chrlist' are used by \s-1RSEM\s0 internally. .PP \&\fB'reference_name.transcripts.fa'\fR 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. .PP \&\fB'reference_name.idx.fa' and 'reference_name.n2g.idx.fa'\fR 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. \s-1RSEM\s0 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 \s-1BAM\s0 files generated by \s-1RSEM\s0 in \s-1IGV,\s0 'reference_name.idx.fa' should be imported as a \*(L"genome\*(R" (see Visualization section in \s-1README\s0.md for details). .PP If the whole genome is indexed for prior-enhanced \s-1RSEM,\s0 all the index files will be generated with prefix as 'reference_name_prsem'. Selected isoforms for training set are listed in the file 'reference_name_prsem.training_tr_crd' .SH "EXAMPLES" .IX Header "EXAMPLES" 1) Suppose we have mouse RNA-Seq data and want to use the \s-1UCSC\s0 mm9 version of the mouse genome. We have downloaded the \s-1UCSC\s0 Genes transcript annotations in \s-1GTF\s0 format (as mm9.gtf) using the Table Browser and the knownIsoforms.txt file for mm9 from the \s-1UCSC\s0 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 \s-1GTF\s0 files generated from \s-1UCSC\s0's Table Browser do not contain isoform-gene relationship information. For the \s-1UCSC\s0 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'. .PP There are two ways to write the command: .PP .Vb 6 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-bowtie \e \& \-\-bowtie\-path /sw/bowtie \e \& /data/mm9/chr1.fa,/data/mm9/chr2.fa,...,/data/mm9/chrM.fa \e \& /ref/mouse_0 .Ve .PP \&\s-1OR\s0 .PP .Vb 6 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-bowtie \e \& \-\-bowtie\-path /sw/bowtie \e \& /data/mm9 \e \& /ref/mouse_0 .Ve .PP 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: .PP .Vb 8 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-bowtie \e \& \-\-bowtie\-path /sw/bowtie \e \& \-\-bowtie2 \e \& \-\-bowtie2\-path /sw/bowtie2 \e \& /data/mm9 \e \& /ref/mouse_0 .Ve .PP 3) Suppose we want to build \s-1STAR\s0 indices in the above example and save index files under '/ref' with name 'mouse_0'. Assuming \s-1STAR\s0 executable is '/sw/STAR', the command will be: .PP .Vb 7 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-star \e \& \-\-star\-path /sw/STAR \e \& \-p 8 \e \& /data/mm9/chr1.fa,/data/mm9/chr2.fa,...,/data/mm9/chrM.fa \e \& /ref/mouse_0 .Ve .PP \&\s-1OR\s0 .PP .Vb 7 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-star \e \& \-\-star\-path /sw/STAR \e \& \-p 8 \e \& /data/mm9 \& /ref/mouse_0 .Ve .PP \&\s-1STAR\s0 genome index files will be saved under '/ref/'. .PP 4) Suppose we want to prepare references for prior-enhanced \s-1RSEM\s0 in the above example. In this scenario, both \s-1STAR\s0 and Bowtie are required to build genomic indices \- \s-1STAR\s0 for RNA-seq reads and Bowtie for ChIP-seq reads. Assuming their executables are under '/sw/STAR' and '/sw/Bowtie', respectively. Also, assuming the mappability file for mouse genome is '/data/mm9.bigWig'. The command will be: .PP .Vb 10 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-star \e \& \-\-star\-path /sw/STAR \e \& \-p 8 \e \& \-\-prep\-pRSEM \e \& \-\-bowtie\-path /sw/Bowtie \e \& \-\-mappability\-bigwig\-file /data/mm9.bigWig \e \& /data/mm9/chr1.fa,/data/mm9/chr2.fa,...,/data/mm9/chrM.fa \e \& /ref/mouse_0 .Ve .PP \&\s-1OR\s0 .PP .Vb 10 \& rsem\-prepare\-reference \-\-gtf mm9.gtf \e \& \-\-transcript\-to\-gene\-map knownIsoforms.txt \e \& \-\-star \e \& \-\-star\-path /sw/STAR \e \& \-p 8 \e \& \-\-prep\-pRSEM \e \& \-\-bowtie\-path /sw/Bowtie \e \& \-\-mappability\-bigwig\-file /data/mm9.bigWig \e \& /data/mm9 \& /ref/mouse_0 .Ve .PP Both \s-1STAR\s0 and Bowtie's index files will be saved under '/ref/'. Bowtie files will have name prefix 'mouse_0_prsem' .PP 5) Suppose we only have transcripts from \s-1EST\s0 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': .PP .Vb 4 \& rsem\-prepare\-reference \-\-transcript\-to\-gene\-map mapping.txt \e \& \-\-polyA \& mm9.fasta \e \& mouse_125 .Ve