annotate arriba.xml @ 9:8c4c97fd0555 draft

"planemo upload for repository https://github.com/jj-umn/tools-iuc/tree/arriba/tools/arriba commit bd2c6bea7cb7dc30ca57f9d69ad49460ddf7f14b"

<tool id="arriba" name="Arriba" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" python_template_version="3.5">
    <description>detect gene fusions from STAR aligned RNA-Seq data</description>
    <macros>
        <import>macros.xml</import>
    </macros>
    <expand macro="requirements" />
    <expand macro="version_command" />
    <command detect_errors="exit_code"><![CDATA[
@GENOME_SOURCE@
#if str($input_params.input_source) == "use_fastq"
    #set $readFilesCommand = ''
    #set $read2 = ''
    #if str($input_params.singlePaired.sPaired) == 'paired_collection':
        #if $input_params.singlePaired.input.forward.is_of_type('fastq.gz', 'fastqsanger.gz'):
            #set $readFilesCommand = '--readFilesCommand zcat'
            #set read1 = 'input_1.fastq.gz'
            #set read2 = 'input_2.fastq.gz'
        #else
            #set read1 = 'input_1.fastq'
            #set read2 = 'input_2.fastq'
        #end if
        ln -sf '${$input_params.singlePaired.input.forward}' ${read1} &&
        ln -sf '${$input_params.singlePaired.input.reverse}' ${read2} &&
    #else
        #if $input_params.singlePaired.input1.is_of_type('fastq.gz', 'fastqsanger.gz'):
            #set $readFilesCommand = '--readFilesCommand zcat'
            #set read1 = 'input_1.fastq.gz'
        #else
            #set read1 = 'input_1.fastq'
        #end if
        ln -sf '$input_params.singlePaired.input1' ${read1} &&
        #if str($input_params.singlePaired.sPaired) == 'paired':
            #set $read2 = $read1.replace('1','2')
            ln -sf '$input_params.singlePaired.input2' ${read2} &&
        #end if
    #end if
    #if str($input_params.index.index_source) == "history"
        #set $star_index_dir = $input_params.index.star_index.extra_files_path
    #else 
        #set $star_index_dir = $input_params.index.arriba_ref.fields.star_index
    #end if
    STAR 
    --runThreadN \${GALAXY_SLOTS:-1} 
    --genomeDir $star_index_dir
    --genomeLoad NoSharedMemory 
    --readFilesIn $read1 $read2
    $readFilesCommand
    --outStd BAM_Unsorted 
    --outSAMtype BAM Unsorted 
    --outSAMunmapped Within 
    --outBAMcompression 0 
    --outFilterMultimapNmax 50 
    --peOverlapNbasesMin 10 
    --alignSplicedMateMapLminOverLmate 0.5 
    --alignSJstitchMismatchNmax 5 -1 5 5 
    --chimSegmentMin 10 
    --chimOutType WithinBAM HardClip 
    --chimJunctionOverhangMin 10 
    --chimScoreDropMax 30 
    --chimScoreJunctionNonGTAG 0 
    --chimScoreSeparation 1 
    --chimSegmentReadGapMax 3 
    --chimMultimapNmax 50 
    | tee Aligned.out.bam |
     arriba 
    -x '/dev/stdin'
#else
     arriba 
    -x '$input_params.input'
    #if $input_params.chimeric
        -c '$input_params.chimeric'
    #end if
#end if
    -a '$genome_assembly'
    -g '$genome_annotation'
    #if $blacklist
        -b '$blacklist'
    #else
        -f 'blacklist'
    #end if
    #if $protein_domains
        -p '$protein_domains'
    #end if
    #if $known_fusions
        -k '$known_fusions'
    #end if
    #if $tags
        -t '$tags'
    #end if
    #if str($wgs.use_wgs) == "yes"
        -d '$wgs.wgs'
        #if $wgs.max_genomic_breakpoint_distance
            -D $wgs.max_genomic_breakpoint_distance
        #end if
    #end if
    -o fusions.tsv
#if $output_fusions_discarded
    -O fusions.discarded.tsv 
#end if
## Arriba options
    #if $options.gtf_features
        -G $options.gtf_features
    #end if
    #if $options.strandedness
        -s $options.strandedness
    #end if
    #if $options.genome_contigs
        -i $options.genome_contigs
    #end if
    #if $options.viral_contigs
        -v $options.viral_contigs
    #end if
    #if $options.max_evalue
        -E $options.max_evalue
    #end if
    #if $options.min_supporting_reads
        -S $options.min_supporting_reads
    #end if
    #if $options.max_mismappers
        -m $options.max_mismappers
    #end if
    #if $options.max_homolog_identity
        -L $options.max_homolog_identity
    #end if
    #if $options.homopolymer_length
        -H $options.homopolymer_length
    #end if
    #if $options.read_through_distance
        -R $options.read_through_distance
    #end if
    #if $options.min_anchor_length
        -A $options.min_anchor_length
    #end if
    #if $options.many_spliced_events
        -M $options.many_spliced_events
    #end if
    #if $options.max_kmer_content
        -m $options.max_kmer_content
    #end if
    #if $options.max_mismatch_pvalue
        -V $options.max_mismatch_pvalue
    #end if
    #if $options.fragment_length
        -F $options.fragment_length
    #end if
    #if $options.max_reads
        -U $options.max_reads
    #end if
    #if $options.quantile
        -Q $options.quantile
    #end if
    #if $options.exonic_fraction
        -e $options.exonic_fraction
    #end if
    #if $options.top_n
        -T $options.top_n
    #end if
    #if $options.covered_fraction
        -C $options.covered_fraction
    #end if
    #if $options.max_itd_length
        -l $options.max_itd_length
    #end if
    $options.duplicate_marking
    $options.fill_discarded_columns
    $options.fill_the_gaps
#if str($input_params.input_source) == "use_fastq"
    && samtools sort -@ \${GALAXY_SLOTS:-1} -m 4G -T tmp -O bam Aligned.out.bam > Aligned.sortedByCoord.out.bam
    && samtools index Aligned.sortedByCoord.out.bam
#elif str($visualization.do_viz) == "yes"
    && samtools sort -@ \${GALAXY_SLOTS:-1} -m 4G -T tmp -O bam '$input_params.input' > Aligned.sortedByCoord.out.bam
    && samtools index Aligned.sortedByCoord.out.bam
#end if
#if str($visualization.do_viz) == "yes"
#set $fusions = 'fusions.tsv'
&& @DRAW_FUSIONS@
#end if
    ]]></command>
    <inputs>
        <conditional name="input_params">
            <param name="input_source" type="select" label="Use output from earlier STAR run or let Arriba running STAR">
                <option value="use_star">Use output from earlier STAR</option>
                <option value="use_fastq">Let Arriba control running STAR</option>
            </param>
            <when value="use_star">
                <param name="input" argument="-x" type="data" format="sam,bam,cram" label="STAR Aligned.out.sam"/>
                <param name="chimeric" argument="-c" type="data" format="sam,bam,cram" optional="true" label="STAR Chimeric.out.sam">
                    <help><![CDATA[ only required, if STAR was run with the parameter '--chimOutType SeparateSAMold' ]]></help>
                </param>
            </when>
            <when value="use_fastq">
                <conditional name="singlePaired">
                    <param name="sPaired" type="select" label="Single-end or paired-end reads">
                        <option value="single" selected="true">Single-end</option>
                        <option value="paired">Paired-end (as individual datasets)</option>
                        <option value="paired_collection">Paired-end (as collection)</option>
                    </param>
                    <when value="single">
                        <param format="fastq,fasta,fastq.gz,fastqsanger.gz" name="input1" type="data" label="RNA-Seq FASTQ/FASTA file"/>
                    </when>
                    <when value="paired">
                        <param format="fastq,fasta,fastq.gz,fastqsanger.gz" name="input1" type="data" label="RNA-Seq FASTQ/FASTA file, forward reads"/>
                        <param format="fastq,fasta,fastq.gz,fastqsanger.gz" name="input2" type="data" label="RNA-Seq FASTQ/FASTA file, reverse reads"/>
                    </when>
                    <when value="paired_collection">
                        <param format="fastq,fasta,fastq.gz,fastqsanger.gz" name="input" type="data_collection" collection_type="paired" label="RNA-Seq FASTQ/FASTA paired reads"/>
                    </when>
                </conditional>
                <conditional name="index">
                    <param name="index_source" type="select" label="Arriba STAR index source">
                        <option value="history">Arriba STAR index from your history</option>
                        <option value="cached">Use a built-in Arriba STAR index</option>
                    </param>
                    <when value="history">
                        <param name="star_index" argument="--genomeDir" type="data" format="txt" label="Arriba STAR index"
                            help="generated by:  Arriba Reference"/>
                    </when> 
                    <when value="cached">
                        <param name="arriba_ref" type="select" label="Arriba STAR index">
                            <options from_data_table="arriba_indexes">
                            </options>
                        </param>
                    </when> 
                </conditional>

            </when>
        </conditional>
        <expand macro="genome_source" />
        <param name="blacklist" argument="-b" type="data" format="tabular,tabular.gz" optional="true" label="File containing blacklisted ranges."/>
        <param name="protein_domains" argument="-p" type="data" format="gff3" optional="true" label="File containing protein domains"/>
        <param name="known_fusions" argument="-k" type="data" format="tabular,tabular.gz"  optional="true" label="File containing known fusions">
            <help><![CDATA[ file two TAB separated columns: five-prime region three-prime region ]]></help>
        </param>
        <param name="tags" argument="-t" type="data" format="tabular" optional="true" label="File containing tag names for a fusion."
               help="This can be the known fusions if that input has a third column with a name"/>
        <conditional name="wgs">
            <param name="use_wgs" type="select" label="Use whole-genome sequencing data">
                <option value="no">no</option>
                <option value="yes">Yes</option>
            </param>
            <when value="yes">
                <param name="wgs" argument="-d" type="data" format="tabular" label="whole-genome sequencing structural variant data"
                       help="These coordinates serve to increase sensitivity towards weakly expressed fusions and to eliminate fusions with low evidence."/>
                <param name="max_genomic_breakpoint_distance" argument="-D" type="integer" value="100000" label="Max genomic breakpoint distance"
                       help="determines how far a genomic breakpoint may be away from a transcriptomic breakpoint to consider it as a related event."/>
            </when>
            <when value="no"/>
        </conditional>
        <section name="options" expanded="false" title="Arriba Options">
            <param name="gtf_features" argument="-G" type="text" value="" optional="true" label="Names of features in the GTF annotation file">
                <help>Commma or SPACE separated list, default: gene_name=gene_name gene_id=gene_id transcript_id=transcript_id feature_exon=exon feature_CDS=CDS</help> 
                <validator type="regex" message="">^(gene_name|gene_id|transcript_id|feature_exon|feature_CDS)=[^ ,]+([ ,](gene_name|gene_id|transcript_id|feature_exon|feature_CDS)=[^ ,]+)?$</validator>
            </param>
            <param name="strandedness" argument="-s" type="select" optional="true" label="Whether a strand-specific protocol was used for library preparation">
                <help>When unstranded data is processed, the strand can sometimes be inferred from splice-patterns. But in unclear situations, stranded data helps resolve ambiguities.</help>
                <option value="auto">auto</option>
                <option value="yes">yes</option>
                <option value="no">no</option>
                <option value="reverse">reverse</option>
            </param>
            <param name="genome_contigs" argument="-i" type="text" value="" optional="true" label="Comma-/space-separated list of interesting contigs">
                <help>Comma-/space-separated list of interesting contigs. 
                      Fusions between genes on other contigs are ignored. Contigs can be specified with or without the prefix "chr". 
                      Asterisks (*) are treated as wild-cards.
                      Default: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 X Y AC_* NC_*
                </help>
            </param>
            <param name="viral_contigs" argument="-v" type="text" value="" optional="true" label="Comma-/space-separated list of viral contigs">
                <help>Comma-/space-separated list of viral contigs. 
                      Asterisks (*) are treated as wild-cards.
                      Default: AC_* NC_*
                </help>
            </param>
            <param name="max_evalue" argument="-E" type="float" value="" optional="true" label="Max e-value threahold">
                <help>Arriba estimates the number of fusions with a given number of supporting
                      reads which one would expect to see by random chance. If the expected number
                      of fusions (e-value) is higher than this threshold, the fusion is
                      discarded by the 'relative_support' filter. Note: Increasing this
                      threshold can dramatically increase the number of false positives and may
                      increase the runtime of resource-intensive steps. Fractional values are possible.
                       Default: 0.300000
                </help>
            </param>

            <param name="min_supporting_reads" argument="-S" type="integer" value="" min="1" optional="true" label="Min supporting reads">
                <help>discard all fusions with fewer than this many supporting reads (split reads and discordant mates combined).
                      Default: 2
                </help>
            </param>
            <param name="max_mismappers" argument="-m" type="float" value="" min="0." max="1.0" optional="true" label="Max mismappers threshold">
                <help>When more than this fraction of supporting reads turns out to be mismappers, 
                      the 'mismappers' filter discards the fusion. 
                      Default: 0.800000
                </help>
            </param>
            <param name="max_homolog_identity" argument="-L" type="float" value="" min="0." max="1.0" optional="true" label="Max homologs identity threshold">
                <help>Genes with more than the given fraction of sequence identity are
                      considered homologs and removed by the 'homologs' filter.
                      Default: 0.300000
                </help>
            </param>
            <param name="homopolymer_length" argument="-H" type="integer" value="" min="1" optional="true" label="Homopolymer length">
                <help>The 'homopolymer' filter removes breakpoints adjacent to homopolymers of the given length or more.
                      Default: 6
                </help>
            </param>
            <param name="read_through_distance" argument="-R" type="integer" value="" min="1" optional="true" label="Read-through distance">
                <help>The 'read_through' filter removes read-through fusions
                      where the breakpoints are less than the given distance away from each other.
                      Default: 10000
                </help>
            </param>
            <param name="min_anchor_length" argument="-A" type="integer" value="" min="1" optional="true" label="Min anchor length">
                <help>Alignment artifacts are often characterized by split reads coming
                      from only one gene and no discordant mates. Moreover, the split
                      reads only align to a short stretch in one of the genes. The
                      'short_anchor' filter removes these fusions. This parameter sets
                      the threshold in bp for what the filter considers short.
                      Default: 23
                </help>
            </param>
            <param name="many_spliced_events" argument="-M" type="integer" value="" min="1" optional="true" label="Many spliced events">
                <help>The 'many_spliced' filter recovers fusions between genes that
                      have at least this many spliced breakpoints.
                      Default: 4
                </help>
            </param>
            <param name="max_kmer_content" argument="-m" type="float" value="" min="0." max="1.0" optional="true" label="Max kmer content">
                <help>The 'low_entropy' filter removes reads with repetitive 3-mers. If
                      the 3-mers make up more than the given fraction of the sequence, then
                      the read is discarded.
                      Default: 0.600000
                </help>
            </param>

            <param name="max_mismatch_pvalue" argument="-V" type="float" value="" optional="true" label="Max mismatchrpvalue threahold">
                <help>The 'mismatches' filter uses a binomial model to calculate a
                      p-value for observing a given number of mismatches in a read.
                      If the number of mismatches is too high, the read is discarded.
                      Default: 0.010000
                </help>
            </param>

            <param name="fragment_length" argument="-F" type="integer" value="" min="1" optional="true" label="Single-end fragment length">
                <help>When paired-end data is given, the fragment length is estimated
                      automatically and this parameter has no effect. But when single-end
                      data is given, the mean fragment length should be specified to
                      effectively filter fusions that arise from hairpin structures.
                      Default: 200
                </help>
            </param>
            <param name="max_reads" argument="-U" type="integer" value="" min="1" optional="true" label="Max reads">
                <help>Subsample fusions with more than the given number of supporting reads. This
                      improves performance without compromising sensitivity, as long as the
                      threshold is high. Counting of supporting reads beyond the threshold is
                      inaccurate, obviously.
                      Default: 300
                </help>
            </param>
            <param name="quantile" argument="-Q" type="float" value="" min="0." max="1.0" optional="true" label="Quantile">
                <help>Highly expressed genes are prone to produce artifacts during library preparation.
                      Genes with an expression above the given quantile are eligible for filtering by the 'in_vitro' filter.
                      Default: 0.998000
                </help>
            </param>
            <param name="exonic_fraction" argument="-e" type="float" value="" min="0." max="1.0" optional="true" label="Exonic fraction">
                <help>The breakpoints of false-positive predictions of intragenic events
                      are often both in exons. True predictions are more likely to have at
                      least one breakpoint in an intron, because introns are larger. 
                      If the fraction of exonic sequence between two breakpoints is smaller than
                      the given fraction, the 'intragenic_exonic' filter discards the event.
                      Default: 0.330000
                </help>
            </param>

            <param name="top_n" argument="-T" type="integer" value="" min="1" optional="true" label="top N viral contigs">
                <help>Only report viral integration sites of the top N most highly expressed viral contigs.
                      Default: 5
                </help>
            </param>
            <param name="covered_fraction" argument="-C" type="float" value="" min="0." max="1.0" optional="true" label="Covered fraction">
                <help>Ignore virally associated events if the virus is not fully expressed, 
                      i.e., less than the given fraction of the viral contig is transcribed.
                      Default: 0.150000
                </help>
            </param>
            <param name="max_itd_length" argument="-l" type="integer" value="" min="1" optional="true" label="Maximum length of internal tandem duplications">
                <help>Note: Increasing this value beyond the default can impair performance and lead to many false positives.
                      Default: 100
                </help>
            </param>
            <param name="duplicate_marking" argument="-u" type="boolean" truevalue="-u" falsevalue="" checked="false" label="Use aligners duplicate marking">
                <help>Instead of performing duplicate marking itself, Arriba relies on duplicate marking by a
                      preceding program using the BAM_FDUP flag. This makes sense when unique molecular
                      identifiers (UMI) are used.
                </help>
            </param>
            <param name="fill_discarded_columns" argument="-X" type="boolean" truevalue="-X" falsevalue="" checked="false" label="Fill all fusion.discarded.tsv columns">
                <help>To reduce the runtime and file size, by default, the columns 'fusion_transcript',
                      'peptide_sequence', and 'read_identifiers' are left empty in the file containing
                      discarded fusion candidates (see parameter -O). When this flag is set, this extra
                      information is reported in the discarded fusions file.
                </help>
            </param>
            <param name="fill_the_gaps" argument="-I" type="boolean" truevalue="-I" falsevalue="" checked="false" label="Fill fusion transcript gaps from the assembly">
                <help>If assembly of the fusion transcript sequence from the supporting reads is incomplete
                      (denoted as '...'), fill the gaps using the assembly sequence wherever possible.
                </help>
            </param>
        </section>
        <param name="output_fusions_discarded" argument="-O" type="boolean" truevalue="yes" falsevalue="no" checked="true" label="Output fusions.discarded.tsv"/>
        <conditional name="visualization">
            <param name="do_viz" type="select" label="Generate visualization">
                <option value="yes">Yes</option>
                <option value="no">no</option>
            </param>
            <when value="yes">
                <expand macro="visualization_options" />
            </when>
            <when value="no"/>
        </conditional>

    </inputs>
    <outputs>
        <data name="fusions_tsv" format="tabular" label="${tool.name} on ${on_string}: fusions.tsv" from_work_dir="fusions.tsv"/>
        <data name="discarded_fusions_tsv" format="tabular" label="${tool.name} on ${on_string}: fusions.discarded.tsv" from_work_dir="fusions.discarded.tsv">
            <filter> output_fusions_discarded == True</filter>
        </data> 
        <data name="aligned_bam" format="bam" label="${tool.name} on ${on_string}: Aligned.bam" from_work_dir="Aligned.sortedByCoord.out.bam">
            <filter>input_params['input_source'] == "use_fastq"</filter>
        </data> 
        <data name="fusions_pdf" format="pdf" label="${tool.name} on ${on_string}: fusions.pdf" from_work_dir="fusions.pdf">
            <filter>visualization['do_viz'] == "yes"</filter>
        </data> 
    </outputs>
    <tests>
        <!-- Test 1 - From exisitng BAM -->
        <test> 
            <conditional name="input_params">
                <param name="input_source" value="use_star"/>
                <param name="input" ftype="sam" value="Aligned.out.sam"/>
            </conditional>
            <conditional name="genome">
                <param name="genome_source" value="history"/>
                <param name="assembly" ftype="fasta" value="genome.fasta"/>
                <param name="annotation" ftype="gtf" value="genome.gtf"/>
            </conditional>
            <param name="protein_domains" ftype="gff3" value="protein_domains.gff3"/>
            <conditional name="visualization">
                <param name="do_viz" value="no"/>
                <param name="cytobands" ftype="tabular" value="cytobands.tsv"/>
            </conditional>
            <output name="fusions_tsv">
                <assert_contents>
                    <has_text_matching expression="BCR\tABL1"/>
                </assert_contents>
            </output>
        </test>
        <!-- Test 2 - From exisitng BAM with protein_domains and visualization -->

        <test> 
            <conditional name="input_params">
                <param name="input_source" value="use_star"/>
                <param name="input" ftype="sam" value="Aligned.out.sam"/>
            </conditional>
            <conditional name="genome">
                <param name="genome_source" value="history"/>
                <param name="assembly" ftype="fasta" value="genome.fasta"/>
                <param name="annotation" ftype="gtf" value="genome.gtf"/>
            </conditional>
            <param name="protein_domains" ftype="gff3" value="protein_domains.gff3"/>
            <conditional name="visualization">
                <param name="do_viz" value="yes"/>
                <param name="cytobands" ftype="tabular" value="cytobands.tsv"/>
            </conditional>
            <output name="fusions_tsv">
                <assert_contents>
                    <has_text_matching expression="BCR\tABL1"/>
                </assert_contents>
            </output>
            <output name="fusions_pdf">
                <assert_contents>
                    <has_size value= "64000" delta="5000" />
                </assert_contents>
            </output>
        </test>
        <!-- Test 3 - From exisitng BAM using cached genome source -->
        <test> 
            <conditional name="input_params">
                <param name="input_source" value="use_star"/>
                <param name="input" ftype="sam" value="Aligned.out.sam"/>
            </conditional>
            <conditional name="genome">
                <param name="genome_source" value="cached"/>
                <param name="arriba_ref" value="GRCh38+ENSEMBL93"/>
            </conditional>
            <param name="protein_domains" ftype="gff3" value="protein_domains.gff3"/>
            <conditional name="visualization">
                <param name="do_viz" value="no"/>
                <param name="cytobands" ftype="tabular" value="cytobands.tsv"/>
            </conditional>
            <output name="fusions_tsv">
                <assert_contents>
                    <has_text_matching expression="BCR\tABL1"/>
                </assert_contents>
            </output>
        </test>

    </tests>
    <help><![CDATA[
**Arriba**


Arriba_ is a fast tool to search for aberrant transcripts such as gene fusions.
It is based on chimeric alignments found by the STAR RNA-Seq aligner.


**INPUTS**

See:  https://arriba.readthedocs.io/en/latest/input-files/

  - Alignments

    Arriba takes the main output file of STAR (Aligned.out.bam) as input (parameter -x). If STAR was run with the parameter --chimOutType WithinBAM, then this file contains all the information needed by Arriba to find fusions. When STAR was run with the parameter --chimOutType SeparateSAMold, the main output file lacks chimeric alignments. Instead, STAR writes them to a separate output file named Chimeric.out.sam. In this case, the file needs to be passed to Arriba via the parameter -c in addition to the main output file Aligned.out.bam.

    Arriba extracts three types of reads from the alignment file(s):

      * Split-reads, i.e., reads composed of segments which map in a non-linear way. STAR stores such reads as supplementary alignments.
      * Discordant mates, i.e., paired-end reads which originate from the same fragment but which align in a non-linear way.
      * Alignments which cross the boundaries of annotated genes, because these alignments might arise from focal deletions. In RNA-Seq data deletions of up to several hundred kb are hard to distinguish from splicing. They are represented identically as gapped alignments, because the sizes of many introns are in fact of this order of magnitude. STAR applies a rather arbitrary measure to decide whether a gapped alignment arises from splicing or from a genomic deletion: The parameter --alignIntronMax determines what gap size is still assumed to be a splicing event and introns are used to represent these gaps. Only gaps larger than this limit are classified as potential evidence for genomic deletions and are stored as chimeric alignments. Most STAR-based fusion detection tools only consider chimeric alignments as evidence for gene fusions and are blind to focal deletions, hence. As a workaround, these tools recommend reducing the value of the parameter --alignIntronMax. But this impairs the quality of alignment, because it reduces the scope that STAR searches to find a spliced alignment. To avoid compromising the quality of alignment for the sake of fusion detection, the only solution would be to run STAR twice - once with settings optimized for regular alignment and once for fusion detection. This would double the runtime. In contrast, Arriba does not require to reduce the maximum intron size. It employs a more sensible criterion to distinguish splicing from deletions: Arriba considers all those reads as potential evidence for deletions that span the boundary of annotated genes.

    The alignment files can be in SAM, BAM, and CRAM format. They need not be sorted for Arriba to accept them, but doing so comes with benefits: Often, this reduces the file size. And more importantly, the supporting reads of a fusion can be inspected visually using a genome browser like IGV, which typically requires BAM files to be sorted by coordinate.

    Single-end and paired-end data and even mixtures are supported. Arriba automatically determines the data type on a read-by-read basis using the flag BAM_FPAIRED.


  - Assembly

    Arriba takes the assembly as input (parameter -a) to find mismatches between the chimeric reads and the reference genome, as well as to find alignment artifacts and homologous genes.

    The script download_references.sh can be used to download the assembly. The available assemblies are listed when the script is run without parameters. The user is not restricted to these assemblies, however. Any assembly can be used as long as its coordinates are compatible with one of the supported assemblies (hg19/hs37d5/GRCh37 or hg38/GRCh38 or mm10/GRCm38).

    The assembly must be provided in FastA format and may be gzip-compressed. An index with the file extension .fai must exist only if CRAM files are processed.

  - Annotation

    The gene annotation (parameter -g) is used for multiple purposes:

    annotation of breakpoints with genes
    increased sensitivity for breakpoints at splice-sites
    calculation of transcriptomic distances
    determining the putative orientation of fused genes (i.e., 5' and 3' end)
    GENCODE annotation is recommended over RefSeq annotation, because the former has a more comprehensive annotation of transcripts and splice-sites, which boosts the sensitivity. The file must be provided in GTF format and may be gzip-compressed. It does not need to be sorted.

    The script download_references.sh can be used to download the annotation. The available annotation files are listed when the script is run without parameters. The user is not restricted to these annotation files, however. Any annotation can be used as long as its coordinates are compatible with one of the supported assemblies (hg19/hs37d5/GRCh37 or hg38/GRCh38 or mm10/GRCm38).


  - Blacklist

    It is strongly advised to run Arriba with a blacklist (parameter -b). Otherwise, the false positive rate increases by an order of magnitude. For this reason, using Arriba with assemblies or organisms which are not officially supported is not recommended. At the moment, the supported assemblies are: hg19/hs37d5/GRCh37, hg38/GRCh38, and mm10/GRCm38 (as well as any other assemblies that have compatible coordinates). The blacklists are contained in the release tarballs of Arriba.

    The blacklist removes recurrent alignment artifacts and transcripts which are present in healthy tissue. This helps eliminate frequently observed transcripts, such as read-through fusions between neighboring genes, circular RNAs and other non-canonically spliced transcripts. It was trained on RNA-Seq samples from the Human Protein Atlas, the Illumina Human BodyMap2 , the ENCODE project , the Roadmap Epigenomics project, and the NCT MASTER cohort, a heterogeneous cohort of cancer samples, from which highly recurrent artifacts were identified.

    Blacklists for all supported assemblies are shipped with the download package of Arriba. They can be found in the package as database/blacklist_*.

    The blacklist is a tab-separated file with two columns and may optionally be gzip-compressed. Lines starting with a hash (#) are treated as comments. Each line represents a pair of regions between which events are ignored. A region can be:
      * a 1-based coordinate in the format CONTIG:POSITION, optionally prefixed with the strand (example: +9:56743754). If CONTIG ends on an asterisk (*), the contig with the closest matching name is chosen. 
      * a range in the format CONTIG:START-END, optionally prefixed with a strand (example: 9:1000000-1100000). 
      * the name of a gene given in the provided annotation.  

    In addition, special keywords are allowed for the second column:
      * any: Discard all events if one of the breakpoints matches the given region.
      * split_read_donor: Discard fusions only supported by split reads, if all of them have their anchor in the gene given in the first column. This filter is useful for highly mutable loci, which frequently trigger clipped alignments, such as the immunoglobulin loci or the T-cell receptor loci.
      * split_read_acceptor: Discard events only supported by split reads, if all of them have their clipped segment in the given region.
      * split_read_any: Discard events only supported by split reads, regardless of where the anchor is.
      * discordant_mates: Discard fusions, if they are only supported by discordant mates (no split reads).
      * low_support: Discard events, which have few supporting reads relative to expression (as determined by the filter relative_support), even if there is other evidence that the fusion might be a true positive, nonetheless. This keyword effectively prevents recovery of speculative events by filters such as spliced or many_spliced.
      * filter_spliced: This keyword prevents the filter spliced from being applied to a given region. It is triggered under the same circumstances as the keyword low_support, but additionally requires that the breakpoints be at splice-sites for the event to be discarded. Some breakpoints produce recurrent artifacts, but the second breakpoint is always a different one, such that the pair of breakpoints is not recurrent and cannot be blacklisted. Often, such breakpoints are at splice-sites and the filter spliced tends to recover them. This keyword prevents the filter from doing so.
      * not_both_spliced: This keyword discards events, unless both breakpoints are at splice-sites. This is a strict blacklist criterion, which makes sense to apply to genes which are prone to produce artifacts, because they are highly expressed, for example hemoglobins, collagens, or ribosomal genes.
      * read_through: This keyword discards events, if they could arise from read-through transcription, i.e., the supporting reads are oriented like a deletion and are at most 400 kb apart.


  - Known fusions

    Arriba can be instructed to be particularly sensitive towards events between certain gene pairs by supplying a list of gene pairs (parameter -k). A number of filters are not applied to these gene pairs. This is useful to improve the detection rate of expected or highly relevant events, such as recurrent fusions. Occassionally, this leads to false positive calls. But if high sensitivity is more important than specificity, this might be acceptable. Events which would be discarded by a filter and were recovered due to being listed in the known fusions list are usually assigned a low confidence.

    Known fusions files for all supported assemblies are shipped with the download package of Arriba. They can be found in the package as database/known_fusions_*.

    The file has two columns separated by a tab and may optionally be gzip-compressed. Lines starting with a hash (#) are treated as comments. Each line represents a pair of regions to which very sensitive filtering thresholds are applied. A region can be:

       * a 1-based coordinate in the format CONTIG:POSITION, optionally prefixed with the strand (example: +9:56743754). If CONTIG ends on an asterisk (*), the contig with the closest matching name is chosen.
       * a range in the format CONTIG:START-END, optionally prefixed with a strand (example: 9:1000000-1100000).
       * the name of a gene given in the provided annotation.

    The order of the given regions is important. The region given in the first column is assumed to denote the 5' end of the fusion and the region in the second column to be the 3' end. If Arriba cannot determine with confidence which gene constitutes the 5' and which the 3' end of a fusion prediction, then the order is ignored and the prediction is rescued in both cases.


  - Tags

    Arriba can be supplied with a list of user-defined tags using the parameter -t. Whenever a fusion prediction matches the selection criteria for a tag, the column tags is populated with the respective tag. This feature is useful to annotate known oncogenic fusions, for example.

    The known fusions file shipped with the download package of Arriba can be used for both known fusions and tags. It is constructed in a way that it can be passed as arguments to the parameters -k and -t alike. The former only uses the first two columns, the latter uses all three columns. If a user wants to separate filtering of known fusions and tagging of interesting fusions, different files may be used, however.

    The file has three columns separated by a tab and may optionally be gzip-compressed. Lines starting with a hash (#) are treated as comments. Each line represents a pair of regions to be annotated. The first two columns specify the regions to be annotated; the third column the tag that is used for annotation. Some special characters in the tag are replaced with underscores (_) in Arriba's output file. A region can be:

      * a 1-based coordinate in the format CONTIG:POSITION, optionally prefixed with the strand (example: +9:56743754).
      * a range in the format CONTIG:START-END, optionally prefixed with a strand (example: 9:1000000-1100000).
      * the name of a gene given in the provided annotation.

    The order of the given regions is important. The region given in the first column is assumed to denote the 5' end of the fusion and the region in the second column to be the 3' end.

  - Protein domains

    Protein domain annotation can be passed to Arriba via the parameter -p. The column retained_protein_domains of Arriba's output file is then populated accordingly.

    Protein domain annotation files for all supported assemblies are shipped with the download package of Arriba. They can be found in the package as database/protein_domains_*.

    The file must be in GFF3 format and may optionally be gzip-compressed. The ninth column must at least contain the following attributes:
      * Name=PROTEIN_DOMAIN_NAME;
      * gene_id=GENE_ID;
      * gene_name=GENE_NAME

    The attribute Name is reported in the column retained_protein_domains of Arriba's output file. Some special characters in the name are replaced with underscores (_). The columns gene_id and gene_name are used to match the protein domains to the genes given in the gene annotation. If a match cannot be found, Arriba cannot determine the retained protein domains of the respective gene and a warning is issued. There may be many warnings if RefSeq annotation is used, because the protein domains file distributed with Arriba uses ENSEMBL gene names/IDs.

  - Structural variant calls from WGS

    If whole-genome sequencing (WGS) data is available, the sensitivity and specificity of Arriba can be improved by passing a list of structural variants detected from WGS to Arriba via the parameter -d. This has the following effects:

    Certain filters are overruled or run with extra sensitive settings, when an event is confirmed by WGS data.
    To reduce the false positive rate, Arriba does not report low-confidence events unless they can be matched with a structural variant found in the WGS data.
    Both of these behaviors can be disabled by disabling the filters genomic_support and no_genomic_support, respectively. Providing Arriba with a list of structural variant calls then does not influence the calls, but it still has the benefit of filling the columns closest_genomic_breakpoint1 and closest_genomic_breakpoint2 with the breakpoints of the structural variant which is closest to a fusion. If the structural variant calls were obtained from whole-exome sequencing (WES) data rather than WGS data, the filter no_genomic_support should be disabled, since WES has poor coverage in most regions of the genome, such that many structural variants are missed.

    Two file formats are accepted: a simple four-column format and the standard Variant Call Format (VCF). The format is detected automatically.

      * In case of the simple format, the file must contain four columns separated by tabs. The first two columns contain the breakpoints of the structural variants in the format CONTIG:POSITION. The last two columns contain the orientation of the breakpoints. The accepted values are:

        + downstream or +: the fusion partner is fused downstream of the breakpoint, i.e., at a coordinate higher than the breakpoint
        + upstream or -: the fusion partner is fused at a coordinate lower than the breakpoint
    
        Example:

        ::

          =========== =========== =========== ===========
          5-prime     3-prime     orientation orientation
          =========== =========== =========== ===========
          1:54420491  6:9248349   +           -
          20:46703288 20:46734546 -           +
          17:61499820 20:45133874 +           +
          3:190967119 7:77868317  -           -
          =========== =========== =========== ===========


      * In case of the Variant Call Format, the file must comply with the VCF specification for structural variants. In particular, Arriba requires that the SVTYPE field be present in the INFO column and specify one of the four values BND, DEL, DUP, INV. In addition, for all SVTYPEs other than BND, the END field must be present and specify the second breakpoint of the structural variant. Structural variants with single breakends are silently ignored.

        Arriba checks if the orientation of the structural variant matches that of a fusion detected in the RNA-Seq data. If, for example, Arriba predicts the 5' end of a gene to be retained in a fusion, then a structural variant is expected to confirm this, or else the variant is not considered to be related.

    NOTE: Arriba was designed for alignments from RNA-Seq data. It should not be run on WGS data directly. Many assumptions made by Arriba about the data (statistical models, blacklist, etc.) only apply to RNA-Seq data and are not valid for DNA-Seq data. For such data, a structural variant calling algorithm should be used and the results should be passed to Arriba.


**OPTIONS**

  - Arriba: https://arriba.readthedocs.io/en/latest/command-line-options/#arriba
  - Visualization: https://arriba.readthedocs.io/en/latest/command-line-options/#draw_fusionsr
  - RNA STAR: https://arriba.readthedocs.io/en/latest/workflow/


**OUTPUTS**

See:  https://arriba.readthedocs.io/en/latest/output-files/

  - fusions.tsv

    The file fusions.tsv (as specified by the parameter -o) contains fusions which pass all of Arriba's filters. It should be highly enriched for true predictions. The predictions are listed from highest to lowest confidence. The following paragraphs describe the columns in detail:

      * gene1 and gene2 : gene1 contains the gene which makes up the 5' end of the transcript and gene2 the gene which makes up the 3' end. The order is predicted on the basis of the strands that the supporting reads map to, how the reads are oriented, and splice patterns. Both columns may contain the same gene, if the event is intragenic. If a breakpoint is in an intergenic region, Arriba lists the closest genes upstream and downstream from the breakpoint, separated by a comma. The numbers in parentheses after the closest genes state the distance to the genes. If no genes are annotated for a contig (e.g., for viral genomes), the column contains a dot (.).

      * strand1(gene/fusion) and strand2(gene/fusion) : Each of these columns contains two values seperated by a slash. The strand before the slash reflects the strand of the gene according to the gene annotation supplied to Arriba via the parameter -g. If the breakpoint is in an intergenic region, the value is .. The value after the slash reflects the strand that is transcribed. This does not necessarily match the strand of the gene, namely when the sense strand of a gene serves as the template for transcription. Occassionally, the strand that is transcribed cannot be predicted reliably. In this case, Arriba indicates the lack of information as a dot (.). Arriba uses splice-patterns of the alignments to assign a read to the appropriate originating gene. If a strand-specific library was used, Arriba also evaluates the strandedness in ambiguous situations, for example, when none of the supporting reads overlaps a splice-site.

      * breakpoint1 and breakpoint2 : The columns contain the coordinates of the breakpoints in gene1 and gene2, respectively. If an event is not supported by any split reads but only by discordant mates, the coordinates given here are those of the discordant mates which are closest to the true but unknown breakpoint.

      * site1 and site2 : These columns add information about the location of the breakpoints. Possible values are: 5' UTR, 3' UTR, UTR (overlapping with a 5' UTR as well as a 3' UTR), CDS (coding sequence), exon, intron, and intergenic. The keyword exon is used for non-coding genes or for ambiguous situations where the breakpoint overlaps with both a coding exon and a UTR. If the breakpoint coincides with an exon boundary, the additional keyword splice-site is appended.

      * type : Based on the orientation of the supporting reads and the coordinates of breakpoints, the type of event can be inferred. Possible values are: translocation (between different chromosomes), duplication, inversion, and deletion. If genes are fused head-to-head or tail-to-tail, this is indicated as 5'-5' or 3'-3' respectively. Genes fused in such an orientation cannot yield a chimeric protein, since one of the genes is transcribed from the wrong strand. This type of event is equivalent to the truncation of the genes. The following types of events are flagged with an extra keyword, because they are frequent types of false positives and/or it is not clear if they are somatic or germline variants: Deletions with a size in the range of introns (<400kb) are flagged as read-through, because there is a high chance that the fusion arises from read-through transcription rather than an underlying genomic deletion. Intragenic duplications with both breakpoints at splice-sites are flagged as non-canonical-splicing, because the supporting reads might originate from circular RNAs, which are very abundant even in normal tissue, but manifest as duplications in RNA-Seq data. Internal tandem duplications are flagged as ITD. It is not always clear whether the ITDs observable in RNA-Seq data are somatic or germline variants, because ITDs are abundant in the germline and germline variants cannot be filtered effectively due to lack of a normal control.

      * split_reads1 and split_reads2 : The number of supporting split fragments with an anchor in gene1 or gene2, respectively, is given in these columns. The gene to which the longer segment of the split read aligns is defined as the anchor.

      * discordant_mates : This column contains the number of pairs (fragments) of discordant mates (a.k.a. spanning reads or bridge reads) supporting the fusion.

      * coverage1 and coverage2 : These two columns show the coverage near breakpoint1 and breakpoint2, respectively. The coverage is calculated as the number of fragments near the breakpoint on the side of the breakpoint that is retained in the fusion transcript. Note that the coverage calculation counts all fragments (even duplicates), whereas the columns split_reads1, split_reads2, and discordant_mates only count non-discarded reads. Fragments discarded due to being duplicates or other types of artifacts can be found in the column filters.

      * confidence : Each prediction is assigned one of the confidences low, medium, or high. Several characteristics are taken into account, including: the number of supporting reads, the balance of split reads and discordant mates, the distance between the breakpoints, the type of event, whether the breakpoints are intragenic or not, and whether there are other events which corroborate the prediction, e.g. multiple isoforms or balanced translocations. See section Interpretation of results for further advice on judging the credibility of predictions.

      * reading_frame : This column states whether the gene at the 3' end of the fusion is fused in-frame or out-of-frame. The value stop-codon indicates that there is a stop codon prior to the fusion junction, such that the 3' end is not translated, even if the reading frame is preserved across the junction. The prediction of the reading frame builds on the prediction of the peptide sequence. A dot (.) indicates that the peptide sequence cannot be predicted, for example, because the transcript sequence could not be determined or because the breakpoint of the 5' gene does not overlap a coding region.

      * tags : When a user-defined list of tags is provided via the parameter -t, this column is populated with the provided tag whenever a fusion matches the coordinates specified for the respective tag. When multiple tags match, they are separated by a comma.

      * retained_protein_domains : If Arriba is provided with protein domain annotation using the parameter -p, then this column is populated with protein domains retained in the fusion. Multiple protein domains are separated by a comma. Redundant protein domains are only listed once. After every domain the fraction that is retained is stated as a percentage value in parentheses. The protein domains of the 5' and 3' genes are separated by a pipe symbol (|).

      * closest_genomic_breakpoint1 and closest_genomic_breakpoint2 : When a matched whole-genome sequencing sample is available, one can feed structural variant calls obtained therefrom into Arriba (see parameter -d). Arriba then considers this information during fusion calling, which improves the overall accuracy. These two columns contain the coordinates of the genomic breakpoints which are closest to the transcriptomic breakpoints given in the columns breakpoint1 and breakpoint2. The values in parentheses are the distances between transcriptomic and genomic breakpoints.

      * gene_id1 and gene_id2 : These two columns state the identifiers of the fused genes as given in the gene_id attribute in the GTF file.

      * transcript_id1 and transcript_id2 : For both fused genes, Arriba determines the best matching isoform that is transcribed as part of the fusion. The isoform is selected by how well its annotated exons match the splice pattern of the supporting reads of a fusion.

      * direction1 and direction2 : These columns indicate the orientation of the fusion. A value of downstream means that the partner is fused downstream of the breakpoint, i.e. at a coordinate higher than the breakpoint. A value of upstream means the partner is fused at a coordinate lower than the breakpoint. When the prediction of the strands or of the 5' gene fails, this information gives insight into which parts of the fused genes are retained in the fusion.

      * filters : This column lists the filters which removed one or more of the supporting reads. The section Internal algorithm describes all filters in detail. The number of filtered reads is given in parentheses after the name of the filter. The total number of supporting reads can be obtained by summing up the reads given in the columns split_reads1, split_reads2, discordant_mates, and filters. If a filter discarded the event as a whole (all reads), the number of filtered reads is not stated.

      * fusion_transcript : This column contains the fusion transcript sequence. The sequence is assembled from the supporting reads of the most highly expressed transcript. It represents the transcript isoform that is most likely expressed according to the splice patterns of the supporting reads. The column contains a dot (.), when the sequence could not be predicted. This is the case when the strands or the 5' end of the transcript could not be predicted reliably. The breakpoint is represented as a pipe symbol (|). When non-template bases are inserted between the fused genes, these bases are represented as lowercase letters between two pipes. Reference mismatches (SNPs or SNVs) are indicated as lowercase letters, insertions as bases between brackets ([ and ]), deleted bases as one or more dashes (-), introns as three underscores (___), and ambiguous positions, such as positions with diverse reference mismatches, are represented as ?. Missing information due to insufficient coverage is denoted as an ellipsis (...). If the switch -I is used, then an attempt is made to fill missing information with the assembly sequence. A sequence stretch that was taken from the assembly sequence rather than the supporting reads is wrapped in parentheses (( and )). In addition, when -I is used, the sequence is trimmed to the boundaries of the fused transcripts. The coordinate of the fusion breakpoint relative to the start of the transcript can thus easily be inferred by counting the bases from the beginning of the fusion transcript to the breakpoint character (|). In case the full sequence could be constructed from the combined information of supporting reads and assembly sequence, the start of the fusion transcript is marked by a caret sign (^) and the end by a dollar sign ($). If the full sequence could not be constructed, these signs are missing.

      * peptide_sequence : This column contains the fusion peptide sequence. The sequence is translated from the fusion transcript given in the column fusion_transcript and determines the reading frame of the fused genes according to the transcript isoforms given in the columns transcript_id1 and transcript_id2. Translation starts at the start of the assembled fusion transcript or when the start codon is encountered in the 5' gene. Translation ends when either the end of the assembled fusion transcript is reached or when a stop codon is encountered. If the fusion transcript contains an ellipsis (...), the sequence beyond the ellipsis is trimmed before translation, because the reading frame cannot be determined reliably. The column contains a dot (.), when the transcript sequence could not be predicted or when the precise breakpoints are unknown due to lack of split reads or when the fusion transcript does not overlap any coding exons in the 5' gene or when no start codon could be found in the 5' gene or when there is a stop codon prior to the fusion junction (in which case the column reading_frame contains the value stop-codon). The breakpoint is represented as a pipe symbol (|). If a codon spans the breakpoint, the amino acid is placed on the side of the breakpoint where two of the three bases reside. Codons resulting from non-template bases are flanked by two pipes. Amino acids are written as lowercase characters in the following situations: non-silent SNVs/SNPs, insertions, frameshifts, codons spanning the breakpoint, non-coding regions (introns/intergenic regions/UTRs), and non-template bases. Codons which cannot be translated to amino acids, such as those having invalid characters, are represented as ?.

      * read_identifiers : This column contains the names of the supporting reads separated by commas.

  - fusions.discarded.tsv

    The file fusions.discarded.tsv (as specified by the parameter -O) contains all events that Arriba classified as an artifact or that are also observed in healthy tissue. It has the same format as the file fusions.tsv. 


**VISUALIZATION**

See: https://arriba.readthedocs.io/en/latest/visualization/

  - fusions.pdf

    A PDF file with one page for each predicted fusion. Each page depicts the fusion partners, their orientation, the retained exons in the fusion transcript, statistics about the number of supporting reads, and if the column fusion_transcript has a value an excerpt of the sequence around the breakpoint.

.. image:: draw-fusions-example.png
  :width: 800
  :height: 467


.. _Arriba: https://arriba.readthedocs.io/en/latest/
.. _INPUTS: https://arriba.readthedocs.io/en/latest/input-files/
.. _OUTPUTS: https://arriba.readthedocs.io/en/latest/output-files/
.. _VISUALIZATION: https://arriba.readthedocs.io/en/latest/visualization/
.. _OPTIONS: https://arriba.readthedocs.io/en/latest/command-line-options/

    ]]></help>
    <expand macro="citations" />
</tool>