name: arriba
description: |
  Arriba is a command-line tool for the detection of gene fusions from RNA-Seq data. It was developed for the use in a clinical research setting. Therefore, short runtimes and high sensitivity were important design criteria.

  Arriba is based on the STAR RNA-Seq aligner and post-processes the alignments (output from STAR) to:

  1. detect split reads and discordant mates, which are indicative of structural rearrangements,
  2. find reads supporting gene fusions (i.e., reads spanning the breakpoints of gene fusions),
  3. perform various filtering steps to remove false positives, and
  4. output the final predictions in a standardized format.

  In contrast to many other fusion detection tools, Arriba does not require to reduce the STAR parameter `--alignIntronMax` (maximum intron size). Reducing this parameter impairs detection of long introns and may affect expression quantification. Arriba reliably filters translocation-based false positives even when large maximum intron sizes are used.

  **Important**: Arriba requires BAM files that were aligned with STAR using specific chimeric alignment parameters, particularly `--chimOutType WithinBAM HardClip`. See the [official workflow documentation](https://github.com/suhrig/arriba/blob/master/run_arriba.sh) for the complete set of recommended STAR parameters.
keywords: [Gene fusion, RNA-Seq, Structural variants, Chimeric alignments]
links:
  homepage: https://arriba.readthedocs.io/
  documentation: https://arriba.readthedocs.io/
  repository: https://github.com/suhrig/arriba
references:
  doi: 10.1101/gr.257246.119
license: MIT
requirements:
  commands: [arriba]
authors:
  - __merge__: /src/_authors/robrecht_cannoodt.yaml
    roles: [ author, maintainer ]
argument_groups:
  - name: Inputs
    arguments:
    - name: --bam
      alternatives: -x
      type: file
      description: |
        File in SAM/BAM/CRAM format with main alignments as generated by STAR
        (Aligned.out.sam). **Important**: The BAM file must be generated by STAR with 
        chimeric alignment parameters, specifically `--chimOutType WithinBAM HardClip`. 
        Arriba extracts candidate reads from this file, including both normal and 
        chimeric alignments.
      required: true
      example: Aligned.out.bam
    - name: --genome
      alternatives: -a
      type: file
      description: |
        FastA file with genome sequence (assembly). The file may be gzip-compressed. An 
        index with the file extension .fai must exist only if CRAM files are processed.
      required: true
      example: assembly.fa
    - name: --gene_annotation
      alternatives: -g
      type: file
      description: |
        GTF file with gene annotation. The file may be gzip-compressed.
      required: true
      example: annotation.gtf
    - name: --known_fusions
      alternatives: -k
      type: file
      description: |
        File containing known/recurrent fusions. Some cancer entities are often 
        characterized by fusions between the same pair of genes. In order to boost 
        sensitivity, a list of known fusions can be supplied using this parameter. The list 
        must contain two columns with the names of the fused genes, separated by tabs.
      required: false
      example: known_fusions.tsv
    - name: --blacklist
      alternatives: -b
      type: file
      description: |
        File containing blacklisted events (recurrent artifacts and transcripts 
        observed in healthy tissue).
      required: false
      example: blacklist.tsv
    - name: --structural_variants
      alternatives: -d
      type: file
      description: |
        Tab-separated file with coordinates of structural variants found using 
        whole-genome sequencing data. These coordinates serve to increase sensitivity 
        towards weakly expressed fusions and to eliminate fusions with low evidence. 
      required: false
      example: structural_variants_from_WGS.tsv
    - name: --tags
      alternatives: -t
      type: file
      description: |
        Tab-separated file containing fusions to annotate with tags in the 'tags' column. 
        The first two columns specify the genes; the third column specifies the tag. The 
        file may be gzip-compressed. 
      required: false
      example: tags.tsv
    - name: --protein_domains
      alternatives: -p
      type: file
      description: |
        File in GFF3 format containing coordinates of the protein domains of genes. The
        protein domains retained in a fusion are listed in the column
        'retained_protein_domains'. The file may be gzip-compressed.
      required: false
      example: protein_domains.gff3
  - name: Outputs
    arguments:
      - name: --fusions
        alternatives: -o
        type: file
        direction: output
        description: |
          Output file with fusions that have passed all filters.
        required: true
        example: fusions.tsv
      - name: --fusions_discarded
        alternatives: -O
        type: file
        direction: output
        description: |
          Output file with fusions that were discarded due to filtering. 
        required: false
        example: fusions.discarded.tsv
  - name: Arguments
    arguments:
      - name: --max_genomic_breakpoint_distance
        alternatives: -D
        type: long
        description: |
          When a file with genomic breakpoints obtained via 
          whole-genome sequencing is supplied via the --structural_variants
          parameter, this parameter determines how far a 
          genomic breakpoint may be away from a 
          transcriptomic breakpoint to consider it as a 
          related event. For events inside genes, the 
          distance is added to the end of the gene; for 
          intergenic events, the distance threshold is 
          applied as is. Default: 100000.
        required: false
      - name: --strandedness
        alternatives: -s
        type: string
        description: |
          Whether a strand-specific protocol was used for library preparation, 
          and if so, the type of strandedness (auto/yes/no/reverse). When 
          unstranded data is processed, the strand can sometimes be inferred from 
          splice-patterns. But in unclear situations, stranded data helps 
          resolve ambiguities. Default: auto
        choices: ["auto", "yes", "no", "reverse"]
        required: false
      - name: --interesting_contigs
        alternatives: -i
        type: string
        description: |
          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_*
        required: false
        multiple: true
        example: ["1", "2", "AC_*", "NC_*"]
      - name: --viral_contigs
        alternatives: -v
        type: string
        description: |
          List of viral contigs. Asterisks (*) are treated as 
          wild-cards.
          Default: AC_* NC_*
        required: false
        multiple: true
        example: ["AC_*", "NC_*"]
      - name: --disable_filters
        alternatives: -f
        type: string
        description: |
          List of filters to disable. By default all filters are 
          enabled. 
        choices: [ homologs, low_entropy, isoforms, 
          top_expressed_viral_contigs, viral_contigs, uninteresting_contigs, 
          non_coding_neighbors, mismatches, duplicates, no_genomic_support, 
          genomic_support, intronic, end_to_end, relative_support, 
          low_coverage_viral_contigs, merge_adjacent, mismappers, multimappers, 
          same_gene, long_gap, internal_tandem_duplication, small_insert_size, 
          read_through, inconsistently_clipped, intragenic_exonic, 
          marginal_read_through, spliced, hairpin, blacklist, min_support, 
          select_best, in_vitro, short_anchor, known_fusions, no_coverage, 
          homopolymer, many_spliced ]
        required: false
        multiple: true
      - name: --max_e_value
        alternatives: -E
        type: double
        description: |
          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 
        required: false
      - name: --min_supporting_reads
        alternatives: -S
        type: integer
        description: |
          The 'min_support' filter discards all fusions with fewer than 
          this many supporting reads (split reads and discordant mates 
          combined). Default: 2 
        required: false
        example: 2
      - name: --max_mismappers
        alternatives: -m
        type: double
        description: |
          When more than this fraction of supporting reads turns out to be 
          mismappers, the 'mismappers' filter discards the fusion. Default: 
          0.800000
        required: false
        example: 0.8
      - name: --max_homolog_identity
        alternatives: -L
        type: double
        description: |
          Genes with more than the given fraction of sequence identity are 
          considered homologs and removed by the 'homologs' filter. 
          Default: 0.300000 
        required: false
        example: 0.3
      - name: --homopolymer_length
        alternatives: -H
        type: integer
        description: |
          The 'homopolymer' filter removes breakpoints adjacent to 
          homopolymers of the given length or more. Default: 6
        required: false
        example: 6
      - name: --read_through_distance
        alternatives: -R
        type: integer
        description: |
          The 'read_through' filter removes read-through fusions 
          where the breakpoints are less than the given distance away 
          from each other. Default: 10000 
        required: false
        example: 10000
      - name : --min_anchor_length
        alternatives: -A
        type: integer
        description: |
          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 
        required: false
        example: 23
      - name: --many_spliced_events
        alternatives: -M
        type: integer
        description: |
          The 'many_spliced' filter recovers fusions between genes that 
          have at least this many spliced breakpoints. Default: 4
        required: false
        example: 4
      - name: --max_kmer_content
        alternatives: -K
        type: double
        description: |
          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 
        required: false
        example: 0.6
      - name: --max_mismatch_pvalue
        alternatives: -V
        type: double
        description: |
          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 
        required: false
        example: 0.05
      - name: --fragment_length
        alternatives: -F
        type: integer
        description: |
          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 
        required: false
        example: 200
      - name: --max_reads
        alternatives: -U
        type: integer
        description: |
          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 
        required: false
        example: 300
      - name: --quantile
        alternatives: -Q
        type: double
        description: |
          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
        required: false
        example: 0.998
      - name: --exonic_fraction
        alternatives: -e
        type: double
        description: |
          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 
        required: false
        example: 0.33
      - name: --top_n
        alternatives: -T
        type: integer
        description: |
          Only report viral integration sites of the top N most highly expressed viral 
          contigs. Default: 5
        required: false
        example: 5
      - name: --covered_fraction
        alternatives: -C
        type: double
        description: |
          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.050000 
        required: false
        example: 0.05
      - name: --max_itd_length
        alternatives: -l
        type: integer
        description: |
          Maximum length of internal tandem duplications. Note: Increasing 
          this value beyond the default can impair performance and lead to many 
          false positives. Default: 100 
        required: false
        example: 100
      - name: --min_itd_allele_fraction
        alternatives: -z
        type: double
        description: |
          Required fraction of supporting reads to report an internal 
          tandem duplication. Default: 0.070000 
        required: false
        example: 0.07
      - name: --min_itd_supporting_reads
        alternatives: -Z
        type: integer
        description: |
          Required absolute number of supporting reads to report an 
          internal tandem duplication. Default: 10 
        required: false
        example: 10
      - name: --skip_duplicate_marking
        alternatives: -u
        type: boolean_true
        description: |
          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.
      - name: --extra_information
        alternatives: -X
        type: boolean_true
        description: |
          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.
      - name: --fill_gaps
        alternatives: -I
        type: boolean_true
        description: |
          If assembly of the fusion transcript sequence from the supporting reads is incomplete 
          (denoted as '...'), fill the gaps using the assembly sequence wherever possible. 
resources:
  - type: bash_script
    path: script.sh
test_resources:
  - type: bash_script
    path: test.sh
  - type: file
    path: /src/_utils/test_helpers.sh
engines:
  - type: docker
    image: quay.io/biocontainers/arriba:2.5.0--h87b9561_1
    setup:
      - type: docker
        run: |
          arriba -h 2>&1 | head -5 | grep 'Version:' | sed 's/Version:\s\(.*\)/arriba: "\1"/' > /var/software_versions.txt
runners:
  - type: executable
  - type: nextflow