# STAR-Fusion 

STAR-Fusion is a component of the [Trinity Cancer Transcriptome Analysis Toolkit (CTAT)](https://github.com/NCIP/Trinity_CTAT/wiki). 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.

>Our STAR-Fusion manuscript preprint is now available on bioRxiv <http://biorxiv.org/content/early/2017/03/24/120295>

## Installation

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

### Downloading a STAR-Fusion Release (Preferred)

Visit <https://github.com/STAR-Fusion/STAR-Fusion/releases>

and be sure to download the 'FULL' version.  The others are auto-generated by GitHub and are missing required submodules.

### Installing from GitHub Clone (Bleeding-edge code, not preferred):

    %  git clone --recursive https://github.com/STAR-Fusion/STAR-Fusion.git

The --recursive parameter is needed to integrate the required submodules.

### Tools Required:

*  STAR <https://github.com/alexdobin/STAR>
*  some non-standard Perl modules - see below:
  
.

       A typical perl module installation may involve:
       perl -MCPAN -e shell
       install Set::IntervalTree
       install DB_File
       install URI::Escape
 	
>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 several alternative resources for human fusion transcript detection depending on whether you want to use GRCh37 or GRCh38 reference human genomes and corresponding Gencode annotation sets.  Options are available here: <https://data.broadinstitute.org/Trinity/CTAT_RESOURCE_LIB/>, so choose one, and below we refer to it as 'CTAT_resource_lib.tar.gz'.   The gene annotations in each case are restricted to the protein-coding and lincRNA transcripts.


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.  FusionFilter comes included in the STAR-Fusion software.


## Preparing the genome resource lib

If you downloaded the large (30G) 'prebuilt' resource lib, then just untar/gz the archive and use it directly. 

Otherwise, if you downloaded the small (~2G) unprocessed resource lib, then you'll need to prep it for use with STAR-fusion as follows: 

     tar xvf CTAT_resource_lib.tar.gz

     cd 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/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/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/CTAT_resource_lib \
                 -J Chimeric.out.junction \
                 --output_dir star_fusion_outdir

>Note, include the --left_fq and --right_fq parameters along with the -J Chimeric.out.junction in order to compute the FFPM (normalized fusion fragments per million total rna-seq fragments) values in your summary report. Otherwise, you'll just get evidence fragment counts without the normalized values.

## 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:

```
#FusionName                  JunctionReadCount  SpanningFragCount  SpliceType           LeftGene                        LeftBreakpoint    RightGene                        RightBreakpoint   LargeAnchorSupport  LeftBreakDinuc  LeftBreakEntropy  RightBreakDinuc  RightBreakEntropy  J_FFPM     S_FFPM
THRA--AC090627.1             27                 93                 ONLY_REF_SPLICE      THRA^ENSG00000126351.8          chr17:38243106:+  AC090627.1^ENSG00000235300.3     chr17:46371709:+  YES_LDAS            GT              1.8892            AG               1.9656             5372.0653  18503.7803
THRA--AC090627.1             5                  93                 ONLY_REF_SPLICE      THRA^ENSG00000126351.8          chr17:38243106:+  AC090627.1^ENSG00000235300.3     chr17:46384693:+  YES_LDAS            GT              1.8892            AG               1.4295             994.8269   18503.7803
ACACA--STAC2                 12                 51                 ONLY_REF_SPLICE      ACACA^ENSG00000132142.15        chr17:35479453:-  STAC2^ENSG00000141750.6          chr17:37374426:-  YES_LDAS            GT              1.9656            AG               1.9656             2387.5846  10147.2344
RPS6KB1--SNF8                10                 43                 ONLY_REF_SPLICE      RPS6KB1^ENSG00000108443.9       chr17:57970686:+  SNF8^ENSG00000159210.5           chr17:47021337:-  YES_LDAS            GT              1.3753            AG               1.8323             1989.6538  8555.5113
TOB1--SYNRG                  8                  30                 ONLY_REF_SPLICE      TOB1^ENSG00000141232.4          chr17:48943419:-  SYNRG^ENSG00000006114.11         chr17:35880751:-  YES_LDAS            GT              1.4566            AG               1.8892             1591.7230  5968.9614
VAPB--IKZF3                  4                  46                 ONLY_REF_SPLICE      VAPB^ENSG00000124164.11         chr20:56964573:+  IKZF3^ENSG00000161405.12         chr17:37934020:-  YES_LDAS            GT              1.9656            AG               1.7819             795.8615   9152.4075
ZMYND8--CEP250               2                  44                 ONLY_REF_SPLICE      ZMYND8^ENSG00000101040.15       chr20:45852970:-  CEP250^ENSG00000126001.11        chr20:34078463:+  NO_LDAS             GT              1.8295            AG               1.8062             397.9308   8754.4767
AHCTF1--NAAA                 3                  38                 ONLY_REF_SPLICE      AHCTF1^ENSG00000153207.10       chr1:247094880:-  NAAA^ENSG00000138744.10          chr4:76846964:-   YES_LDAS            GT              1.7232            AG               1.8062             596.8961   7560.6844
VAPB--IKZF3                  1                  46                 ONLY_REF_SPLICE      VAPB^ENSG00000124164.11         chr20:56964573:+  IKZF3^ENSG00000161405.12         chr17:37944627:-  NO_LDAS             GT              1.9656            AG               1.8892             198.9654   9152.4075
VAPB--IKZF3                  1                  46                 ONLY_REF_SPLICE      VAPB^ENSG00000124164.11         chr20:56964573:+  IKZF3^ENSG00000161405.12         chr17:37922746:-  NO_LDAS             GT              1.9656            AG               1.9329             198.9654   9152.4075
STX16--RAE1                  4                  33                 ONLY_REF_SPLICE      STX16^ENSG00000124222.17        chr20:57227143:+  RAE1^ENSG00000101146.8           chr20:55929088:+  YES_LDAS            GT              1.9899            AG               1.9656             795.8615   6565.8575
```

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 encompass 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.

Since the number of fusion-supporting reads depends on both the expression of the fusion transcript and the number of reads sequenced, we provide normalized measures of the split reads and spanning fragments as FFPM (fusion fragments per million total reads) measures:  J_FFPM for the junction/split reads and S_FFPM for the spanning fragments.  If you sum them (a column not yet included but will be soon), you can filter based on this value to remove many lowly expressed and likely artifact fusions.  A filter of 0.1 sum FFPM tends to be very effective.

The 'LargeAnchorSupport' column indicates whether there are split reads that provide 'long' (set to length of 25 bases) alignments on both sides of the putative breakpoint.  Those fusions supported only by split reads (no spanning fragments) and lack LargeAnchorSupport are often highly suspicious and tend to be false positives.  Those with LargeAnchorSupport are labeled as 'YES_LDAS' (where LDAS = long double anchor support.... yes, more jargon).

'SpliceType' indicates whether the proposed breakpoint occurs at reference exon junctions as provided by the reference transcript structure annotations (ex. gencode).

The .final.abridged.FFPM 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.

If there are alternatively spliced isoforms for fusion transcripts, the same fusion pair will be listed as multiple entries but with different breakpoints identified.


## 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 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/CTAT_resource_lib \
                   --verbose_level 2  


## Further Inspection, Visualization, and Validation?

We have a companion tool called FusionInspector <https://github.com/FusionInspector/FusionInspector/wiki> that provides a more in-depth view of the evidence supporting the predicted fusions.  FusionInspector can also run [Trinity](http://trinityrnaseq.github.io) to de novo reconstruct your predicted fusion transcripts based on the identified fusion-supporting RNA-Seq reads.

## Want to use Docker?

We provide a Docker image that contains all software pre-installed for running STAR, STAR-Fusion, and FusionInspector, and it's available here: https://hub.docker.com/r/trinityctat/ctatfusion/

If you have docker installed, you can pull the image like so:

    docker pull trinityctat/ctatfusion

STAR-Fusion could be run like so via Docker:

    docker run -v `pwd`/../:/data --rm trinityctat/ctatfusion \
          /usr/local/src/STAR-Fusion-v1.0.0/STAR-Fusion \
          --left_fq /data/testing/reads_1.fq.gz \
          --right_fq /data/testing/reads_2.fq.gz \
          --genome_lib_dir /data/GRCh37_gencode_v19_CTAT_lib_July272016_prebuilt \
          -O /data/testing/test_docker_outdir/StarFusionOut

and FusionInspector could be run like so, given the output from STAR-Fusion as run above:

    docker run -v `pwd`/../:/data --rm trinityctat/ctatfusion \
           /usr/local/src/FusionInspector-v1.0.1/FusionInspector \
           --fusions /data/testing/test_docker_outdir/StarFusionOut/star-fusion.fusion_candidates.final.abridged.FFPM \
           --left_fq /data/testing/reads_1.fq.gz \
           --right_fq /data/testing/reads_2.fq.gz \
           --genome_lib /data/GRCh37_gencode_v19_CTAT_lib_July272016_prebuilt \
           --out_prefix finspector \
           --out_dir /data/testing/test_docker_outdir/FusionInspectorOut \
           --include_Trinity


## Contact Us

Questions, comments, etc?

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

## Acknowledgements

This effort was largely inspired by earlier work done by Nicolas Stransky in the landmark publication "The landscape of kinase fusions in cancer" by [Stransky et al., Nat Commun 2014](http://www.ncbi.nlm.nih.gov/pmc/articles/PMC4175590/), in addition to very nice work done by Daniel Nicorici with his [FusionCatcher software](http://biorxiv.org/content/early/2014/11/19/011650).

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

