# Installing STAR-Fusion

STAR-Fusion requires the following software and data resources to be installed. 

>Note, if you can use our [Docker](https://github.com/STAR-Fusion/STAR-Fusion/wiki#Docker) or [Singularity](https://github.com/STAR-Fusion/STAR-Fusion/wiki#Singularity) images, then you'll have all the software pre-installed and can hit the ground running. Just install the [data resources required](#data_resources_required) below.

#### 1. 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.

After unpacking the tar.gz file, run 'make' in the base installation directory.

#### 2. Installing from GitHub Clone:

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

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

Type 'make' in the base installation directory.


### Tools Required:

*  STAR <https://github.com/alexdobin/STAR>
*  samtools <http://www.htslib.org/download/>
*  possibly some non-standard Perl modules - see below:
  
.

       A typical perl module installation may involve:
       perl -MCPAN -e shell
       install DB_File
       install URI::Escape
       install Set::IntervalTree
       install Carp::Assert
       install JSON::XS
       install PerlIO::gzip

If you plan on using the included FusionInspector for 'inspect' or 'validate' modes, please install the [FusionInspector dependencies](https://github.com/FusionInspector/FusionInspector/wiki/installing-FusionInspector).


<a name='ComputeRequirements'></a>
## Computing / Hardware Requirements and Execution Times

### Memory 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.

When the '--FusionInspector validate' mode is used, memory requirements can increase to 40G or 50G.  If '--FusionInspector inspect' mode is used, additional RAM should generally not be required.
 

### Execution times

Execution times are largely determined by how long it takes for STAR to align reads. The fusion-finding component generally takes minutes on large samples.  If '--FusionInspector validate' mode is used, then roughly double the total execution time, as STAR is needed to perform an additional full alignment of the reads in FusionInspector mode.

<a name='data_resources_required'></a>
### 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](https://www.gencodegenes.org/) 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 'plug-n-play' libs are that... just download, unpack it (tar -zxvf filename.tar.gz)   

The latest release of STAR-Fusion will be compatible with the currently available version of the [CTAT resource genome lib](<https://data.broadinstitute.org/Trinity/CTAT_RESOURCE_LIB/>).  For older versions of STAR-Fusion, see the [STAR-Fusion release and CTAT Genome Lib Compatibility Matrix](STAR-Fusion-release-and-CTAT-Genome-Lib-Compatibility-Matrix).


>**If you're looking to apply STAR-Fusion using a different target**, you'll need to generate the required resources as described by our [ctat-genome-lib-builder](https://github.com/NCIP/ctat-genome-lib-builder/wiki) resource builder.  The ctat-genome-lib-builder comes included in the STAR-Fusion software.


## Preparing the genome resource lib

**Preferred**  If you downloaded the large (30G) 'plug-n-play' resource lib, then just untar/gz the archive and use it directly.  

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

     (only if building from source archive - note plug-n-play is preferred!)   

     %  tar xvf CTAT_resource_lib.tar.gz

     %  cd CTAT_resource_lib/

     %  $STAR_FUSION_HOME/ctat-genome-lib-builder/prep_genome_lib.pl \
                             --genome_fa ref_genome.fa \
                             --gtf gencode.*.annotation.gtf \
                             --fusion_annot_lib fusion_lib.*.dat.gz \
                             --annot_filter_rule AnnotFilterRule.pm \
                             --pfam_db current \
                             --dfam_db human \
                             --human_gencode_filter

Note, the above builder has a number of additional software requirements including blast, hmmer, among others.  See the [ctat-genome-lib-builder wiki](https://github.com/NCIP/ctat-genome-lib-builder/wiki) for full installation details.  Using our Docker or Singularity images for doing this step is easiest and preferred if you're planning to go this route.  For example, **if you have Singularity installed**, you can leverage the singularity image we provide on our release downloads page and run like so:

    
    % singularity exec -e star-fusion.simg \
       /usr/local/src/STAR-Fusion/ctat-genome-lib-builder/prep_genome_lib.pl \
          --genome_fa genome.primary.fa \
          --gtf gencode.*.annotation.gtf \
          --fusion_annot_lib fusion_lib.*.dat.gz \
          --annot_filter_rule AnnotFilterRule.pm \
          --pfam_db current \
          --dfam_db human \
          --human_gencode_filter  # include only if human data



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