# STAR-Fusion 

STAR-Fusion uses the [STAR](https://github.com/alexdobin/STAR) aligner to identify candidate fusion transcripts supported by Illumina reads.  STAR-Fusion further processes the output generated by the STAR aligner to map junction reads and spanning reads to a reference annotation set.


## Installation

In addition to STAR-Fusion, the following tools and resource data sets must be installed:

### Tools Required:

*  STAR <https://github.com/alexdobin/STAR>
*  the following non-standard Perl modules from CPAN: Set/IntervalTree.pm and DB_File.pm
  
    A typical perl module installation may involve:
    perl -MCPAN -e shell
      install Set::IntervalTree
      install DB_File
 	
>The Set::IntervalTree module tends to install trouble-free on Linux.  Note, if you have trouble installing Set::IntervalTree on Mac OS X (as I did), try the following:  download the tarball from the http://search.cpan.org/~benbooth/Set-IntervalTree-0.02/lib/Set/IntervalTree.pm, run the perl Makefile.pl, then edit the generated 'Makefile' and remove all occurrences of '-arch i386'. Then try 'make', 'make test', and finally 'make install'.

## Computing / Hardware requirements

If you're planning to run STAR to align reads to the human genome, then you'll need ~30G RAM.   If you've already run STAR and are just planning on running STAR-Fusion given the existing STAR outputs, then modest resources are required and it should run on any commodity hardware.


### Data Resources Required:

A reference genome and corresponding protein-coding gene annotation set, including blast-matching gene pairs must be provided to STAR-Fusion.  We provide these resources for human fusion transcript detection using Hg19 and gencode.v19 annotations as [Hg19_CTAT_resource_lib.tar.gz](https://data.broadinstitute.org/Trinity/CTAT_RESOURCE_LIB/Hg19_CTAT_resource_lib.tar.gz).  If you're looking to apply STAR-Fusion using a different target, you'll need to generate the required resources as described by our [FusionFilter](http://FusionFilter.github.io) resource builder.

Assuming the use of our Hg19_CTAT_resource_lib.tar.gz resource data set, build the various indexes required by STAR-Fusion like so:

     tar xvf Hg19_CTAT_resource_lib.tar.gz

     cd Hg19_CTAT_resource_lib/

     $STAR_FUSION_HOME/FusionFilter/prep_genome_lib.pl \
                             --genome_fa ref_genome.fa \
                             --gtf ref_annot.gtf \
                             --blast_pairs blast_pairs.outfmt6.gz


Once the build process completes successfully, you can then refer to the above like so with STAR-Fusion:

       STAR-Fusion --genome_lib_dir /path/to/your/Hg19_CTAT_resource_lib   ...

       # full usage info provided below.



## Running STAR-Fusion starting with FASTQ files:

Given paired-end of FASTQ files, run STAR-Fusion like so:

     STAR-Fusion --genome_lib_dir /path/to/your/Hg19_CTAT_resource_lib \
                 --left_fq reads_1.fq \
                 --right_fq reads_2.fq \
                 --output_dir star_fusion_outdir
                 

## Alternatively, running STAR yourself, and then running STAR-Fusion using the existing outputs:

It's not always the case that you want to have STAR-Fusion run STAR directly, as you may have already run STAR earlier on, or prefer to run STAR separately to use the outputs in other processes such as for expression estimates or variant detection.

Parameters that we recommend for running STAR as part of STAR-Fusion are as follows:

     STAR --genomeDir ${star_index_dir} \                                                                                     
          --readFilesIn ${left_fq_filename} ${right_fq_filename} \                                                                      
          --twopassMode Basic \                                                                                                      
          --outReadsUnmapped None \                                                                                                  
          --chimSegmentMin 12 \                                                                                                    
          --chimJunctionOverhangMin 12 \                                                                                           
          --alignSJDBoverhangMin 10 \                                                                                              
          --alignMatesGapMax 200000 \                                                                                             
          --alignIntronMax 200000 \                                                                                                
          --chimSegmentReadGapMax parameter 3 \                                                                                    
          --alignSJstitchMismatchNmax 5 -1 5 5 \
          --runThreadN ${THREAD_COUNT} \                                                                                                           
          --limitBAMsortRAM 31532137230 \                                                                                           
          --outSAMtype BAM SortedByCoordinate 

This will (in part) generate a file called 'Chimeric.out.junction', which is used by STAR-Fusion like so:

     STAR-Fusion --genome_lib_dir /path/to/your/Hg19_CTAT_resource_lib \
                 -J Chimeric.out.junction \
                 --output_dir star_fusion_outdir


## Output from STAR-Fusion

The output from STAR-Fusion is found as a tab-delimited file named 'star-fusion.fusion_candidates.final.abridged', and has the following format:

```
#fusion_name    JunctionReads   SpanningFrags   Splice_type     LeftGene        LeftBreakpoint  RightGene       RightBreakpoint
CACNG6--RPLP2   31      0       INCL_NON_REF_SPLICE     CACNG6^ENSG00000130433.3        chr19:54515460:+        RPLP2^ENSG00000177600.4 chr11:810019:+  
ACACA--STAC2    12      51      ONLY_REF_SPLICE ACACA^ENSG00000132142.15        chr17:35479453:-        STAC2^ENSG00000141750.6 chr17:37374426:-        
RPS6KB1--SNF8   9       42      INCL_NON_REF_SPLICE     RPS6KB1^ENSG00000108443.9       chr17:57970686:+        SNF8^ENSG00000159210.5  chr17:47021337:-        
VAPB--IKZF3     3       46      ONLY_REF_SPLICE VAPB^ENSG00000124164.11 chr20:56964573:+        IKZF3^ENSG00000161405.12        chr17:37934020:-        
VAPB--IKZF3     2       46      ONLY_REF_SPLICE VAPB^ENSG00000124164.11 chr20:56964573:+        IKZF3^ENSG00000161405.12        chr17:37922746:-        
ZMYND8--CEP250  2       44      ONLY_REF_SPLICE ZMYND8^ENSG00000101040.15       chr20:45852970:-        CEP250^ENSG00000126001.11       chr20:34078463:+        
TOB1--SYNRG     5       30      INCL_NON_REF_SPLICE     TOB1^ENSG00000141232.4  chr17:48943419:-        SYNRG^ENSG00000006114.11        chr17:35880751:-        
STX16--RAE1     4       33      ONLY_REF_SPLICE STX16^ENSG00000124222.17        chr20:57227143:+        RAE1^ENSG00000101146.8  chr20:55929088:+        
RPS6KB1--SNF8   1       42      ONLY_REF_SPLICE RPS6KB1^ENSG00000108443.9       chr17:57970686:+        SNF8^ENSG00000159210.5  chr17:4702133
```

The JunctionReads column indicates the number of RNA-Seq fragments containing a read that aligns as a split read at the site of the putative fusion junction.   

The SpanningFrags column indicates the number of RNA-Seq fragments that span the fusion junction such that one read of the pair aligns to a different gene than the other paired-end read of that fragment.

>Those predictions that have very few JunctionReads and SpanningReads are going to be enriched for false positives. Note, depending on the site of the fusion breakpoint and length of the reads, it may not be possible to have SpanningFragments and all evidence may show up in the form of JunctionReads.

The .final.abridged output file contents are shown above. See the unabridged '.final' output file for the identity of the RNA-Seq fragments identified as junction or spanning fragments.



## Example data and execution:

In the included testing/ directory, you'll find a small sample of fastq reads from a tumor sample.  Find fusions using the Hg19 resource set like so:

    cd testing/
     
    ../STAR-Fusion --left_fq reads_1.fq.gz --right_fq reads_2.fq.gz \
                   -O star_fusion_outdir \
                   --genome_lib_dir  /path/to/your/Hg19_CTAT_resource_lib \
                   --verbose_level 2  


## Contact Us

Questions, comments, etc?

Visit our Google group <https://groups.google.com/forum/#!forum/star-fusion>

## Acknowledgements

This effort was largely inspired by earlier work done by Nicolas Stransky and by Daniel Nicorici.

STAR-Fusion is contributed by Brian Haas (@Broad Institute), in collaboration with Alex Dobin (@CSHL).

