# FusionInspector: In silico Validation of Fusion Transcript Predictions

<img src="images/FusionInspectorsvg.png" width="200" />

FusionInspector is a component of the [Trinity Cancer Transcriptome Analysis Toolkit (CTAT)](https://github.com/NCIP/Trinity_CTAT/wiki). FusionInspector assists in fusion transcript discovery by performing a supervised analysis of fusion predictions, attempting to recover and re-score evidence for such predictions. As of July, 2017, FusionInspector has been included as a component of the [STAR-Fusion](https://github.com/STAR-Fusion/STAR-Fusion/wiki)  suite.

Given a list of candidate fusion genes (as derived from running any fusion transcript prediction tool, such as [Prada](http://bioinformatics.mdanderson.org/main/PRADA:Overview), [FusionCatcher](http://biorxiv.org/content/early/2014/11/19/011650), [SoapFuse](http://soap.genomics.org.cn/soapfuse.html), [TophatFusion](http://ccb.jhu.edu/software/tophat/fusion_index.html), [DISCASM/GMAP-Fusion](https://github.com/DISCASM/DISCASM/wiki), [STAR-Fusion](https://github.com/STAR-Fusion/STAR-Fusion/wiki), or other), FusionInspector extracts the genomic regions for the fusion partners and constructs mini-fusion-contigs containing the pairs of genes in their proposed fused orientation.  The original reads are aligned to these candidate fusion contigs; fusion-supporting reads that would normally align as discordant pairs or split reads should align as concordant 'normal' reads in this fusion-gene context.  Those reads supporting each fusion (spanning fragments and fusion-breakpoint-containing reads) are identified, reported, and scored accordingly.

Optionally, Trinity de novo transcriptome assembly can be executed as part of the FusionInspector routine in order to de novo reconstruct fusion transcripts from the mapped reads.

Outputs generated by FusionInspector are easily viewed in a genome browser such as IGV so that the evidence for fusion transcripts can be manually assessed for read and alignment quality.

## Installation Requirements

### Software requirements:

FusionInspector requires the following companion software tools to be installed:

* [FusionInspector](https://github.com/FusionInspector/FusionInspector/releases) software itself, of course.

* [STAR](https://github.com/alexdobin/STAR) (obtain the very latest development version of STAR via 'git clone')

* [Trinity](https://github.com/trinityrnaseq/trinityrnaseq/wiki) (Even if you do not wish to de novo assemble fusion transcripts, components of the Trinity software are still required.)

* [samtools](https://sourceforge.net/projects/samtools/files/samtools/) (modern versions, 1.3+)

* [bgzip from the htslib package](https://github.com/samtools/htslib/releases/tag/1.3) 

* And the following non-standard Perl modules:

   * URI::Escape

   * Set::IntervalTree

   * DB_File

>The [cpanm](http://www.cpan.org/modules/INSTALL.html) tool is useful for local installations of these.

**Be sure STAR, samtools, and bgzip are available via your PATH env var setting, and create env var TRINITY_HOME set to the Trinity installation directory.**

### Data requirements

FusionInspector is a component of the [Trinity Cancer Transcriptome Analysis Toolkit](https://github.com/NCIP/Trinity_CTAT/wiki), and as with the other fusion-transcriptome components of CTAT, FusionInspector leverages the [FusionFilter](https://github.com/FusionFilter/FusionFilter/wiki) data resources.  Visit the [FusionFilter](https://github.com/FusionFilter/FusionFilter/wiki) website for links to existing data resources for human fusion transcript detection, or instructions on how to build your own data resources for use with CTAT.


## Running FusionInspector

FusionInspector requires one or more lists of fusion candidates, with each formatted like so, as geneA--geneB:

    B3GNT1--NPSR1
    ZNF709--DYRK1A
    ZNF844--NCBP2
    RBX1--HAPLN2
    FAM180B--TRIM60
    CASP9--ADCYAP1
    HS3ST3A1--C1QTNF2
    OPTC--AP000347.4
    GRIA2--ZW10


We'll call the file containing this list 'fusions.listA.txt'.  Let's assume we have another such list from another source, and we'll call it 'fusions.listB.txt'.

>It's ok to have a tab-delimited file containing other attributes (such as the raw output from some fusion-prediction tool) as long as the first column fits the above format.

Given this list of fusions, we'll run FusionInspector like so:

    FusionInspector --fusions fusions.listA.txt,fusions.listB.txt \
                    --genome_lib /path/to/CTAT_genome_lib \
                    --left_fq rnaseq_1.fq --right_fq rnaseq_2.fq \
                    --out_dir my_FusionInspector_outdir \
                    --out_prefix finspector \
                    --prep_for_IGV

## Output of FusionInspector

The final output of FusionInspector is a file called 'finspector.fusion_predictions.final.abridged.FFPM', which you'll find in the --out_dir specified.  The format of this file is tab-delimited and contains the following fields and formatting:

>Scroll the window below to the right to see all the fields.

```
#FusionName            JunctionReadCount  SpanningFragCount  LeftGene                         LeftLocalBreakpoint  LeftBreakpoint     RightGene                        RightLocalBreakpoint  RightBreakpoint    SpliceType                    LargeAnchorSupport  NumCounterFusionLeft  NumCounterFusionRight  FAF_left  FAF_right  LeftBreakDinuc  LeftBreakEntropy  RightBreakDinuc  RightBreakEntropy  FFPM
THRA--AC090627.1       88                 97                 THRA^ENSG00000126351.8           11793                chr17:38243106:+   AC090627.1^ENSG00000235300.3     21568                 chr17:46371709:+   ONLY_REF_SPLICE               YES                 24                    0                      0.89      1.00       GT              1.8892            AG               1.9656             8.6326
ACACA--STAC2           62                 45                 ACACA^ENSG00000132142.15         66695                chr17:35479453:-   STAC2^ENSG00000141750.6          81161                 chr17:37374426:-   ONLY_REF_SPLICE               YES                 233                   1                      0.31      0.99       GT              1.9656            AG               1.9656             4.9929
RPS6KB1--SNF8          37                 46                 RPS6KB1^ENSG00000108443.9        1240                 chr17:57970686:+   SNF8^ENSG00000159210.5           26089                 chr17:47021337:-   ONLY_REF_SPLICE               YES                 93                    486                    0.47      0.15       GT              1.3753            AG               1.8323             3.873
TOB1--SYNRG            22                 35                 TOB1^ENSG00000141232.4           2782                 chr17:48943419:-   SYNRG^ENSG00000006114.11         37847                 chr17:35880751:-   ONLY_REF_SPLICE               YES                 104                   49                     0.35      0.54       GT              1.4566            AG               1.8892             2.6598
```


There is also a .final file which contains most of the above fields along with the identity of the reads corresponding to fusion-supporting fragments. This file can be very large, and so the abridged version easier to navigate.

### Fusion Allelic Fraction

The fusion allelic fraction (FAF) is computed as a pragmatic way of estimating the relative expression of the fusion transcript as compared to the alternative non-fused allele of the gene.  The method underlying the calculation is illustrated below:

<img src="images/FAF_computation.png" />

In the above image, there are 2 fusion-supporting fragments (green), there are 3 fragments (blue) that correspond to the non-fused geneA allele, and there is 1 fragment (purple) supporting the non-fused geneB allele.  The fusion allele fraction (FAF) is computed separately for each of the fused genes and reflects the proportion of evidence supporting the fused-allele as compared to the total number of reads at the breakpoint.  While this is not a highly accurate measurement of the ratio of fused vs. non-fused transcripts, it's a useful metric to serve as a proxy for this information.  Accurate measurements would require performing abundance estimation based on knowing the exact structures and lengths of the full-length fused and non-fused isoforms being expressed.  This additional functionality is still pending but will be addressed in a future software release.  

>For now, we use FFPM as our proxy for fusion transcript expression, and FAF as a proxy for relative expression of the fusion transcript to non-fused alleles.

## Visualizing the Fusion Evidence

When the '--prep\_for_IGV' parameter is specified, a number of files as shown below are generated for viewing in the IGV (or other) genome browser:


    finspector.fa : the candidate fusion-gene contigs
    finspector.bed : the reference gene structure annotations for fusion partners
    finspector.junction_reads.bam : alignments of the breakpoint-junction supporting reads.
    finspector.spanning_reads.bam : alignments of the breakpoint-spanning paired-end reads.

An example of viewing a fusion candidate with recovered read evidence using IGV is shown below. 

You can load the 'finspector.fa' as a 'new genome' and then load up the various gtf and bam files for viewing, or simply run a command like so (assuming you have IGV installed and the 'igv.sh' script in your PATH setting):

    %  igv.sh -g `pwd`/finspector.fa \
    `pwd`/finspector.gtf,`pwd`/finspector.spanning_reads.bam,`pwd`/finspector.junction_reads.bam

and the view would look similar to this:

<img src="https://raw.githubusercontent.com/wiki/FusionInspector/FusionInspector/images/finspector_bcr--abl.png" />


where you can readily examine the paired-end and split-read evidence for any of the supported fusions. 


## Example data and execution

See the 'test/' subdirectory and examine the README.txt file included.  Example data and command execution info are provided.


## User support

Contact us on our google group <https://groups.google.com/forum/#!forum/trinity_ctat_users>

## Acknowledgements

FusionInspector is primarily a collaboration between [Brian Haas (Broad Institute)](https://personal.broadinstitute.org/bhaas/) and [Alex Dobin (Cold Spring Harbor Laboratory)](https://scholar.google.com/citations?user=2LAxpBsAAAAJ&hl=en), and developed as part of the [Trinity Cancer Transcriptome Analysis Toolkit](https://github.com/NCIP/Trinity_CTAT/wiki).