name: htseq_count
namespace: mapping
scope: "public"
description: |
  Quantify gene expression for subsequent testing for differential expression.

  This script takes one or more alignment files in SAM/BAM format and a feature file in GFF format and calculates for each feature the number of reads mapping to it. 
  
  See http://htseq.readthedocs.io/en/master/count.html for details.
authors:
  - __merge__: /src/authors/robrecht_cannoodt.yaml
    roles: [ author, maintainer ]
  - __merge__: /src/authors/angela_pisco.yaml
    roles: [ author ]
argument_groups:
  - name: Input
    arguments:
      - type: file
        name: --input
        required: true
        description: Path to the SAM/BAM files containing the mapped reads.
        example: [ "mysample1.BAM", "mysample2.BAM" ]
        multiple: true
        info:
          orig_arg: samfilenames
      - type: file
        name: --reference
        description: Path to the GTF file containing the features.
        example: reference.gtf
        required: true
        info:
          orig_arg: featurefilename
  - name: Output
    arguments:
      - type: file
        name: --output
        description: Filename to output the counts to.
        example: htseq-count.tsv
        direction: output
        required: true
        info:
          orig_arg: --counts_output
      - type: string
        name: --output_delimiter
        description: Column delimiter in output.
        required: false
        example: "\t"
        info:
          orig_arg: --delimiter
      - type: file
        name: --output_sam
        description: |
          Write out all SAM alignment records into SAM/BAM files (one per input file needed), 
          annotating each line with its feature assignment (as an optional field with tag 'XF'). 
          See the -p option to use BAM instead of SAM.
        example: [ "mysample1_out.SAM", "mysample2_out.SAM" ]
        direction: output
        required: false
        multiple: true
        info:
          orig_arg: --samout
      - type: string
        name: --output_sam_format
        choices: [ sam, bam ]
        description: Format to use with the --output_sam argument.
        required: false
        info:
          orig_arg: --samout-format
  - name: Arguments
    arguments:
      - name: --order
        alternatives: [-r]
        type: string
        choices: [pos, name]
        default: name
        description: |
          Sorting order of <alignment_file>. Paired-end sequencing data must be sorted either by position or
          by read name, and the sorting order must be specified. Ignored for single-end data.
        info:
          orig_arg: --order
      - name: --stranded
        alternatives: [-s]
        type: string
        choices: ["yes", "no", "reverse"]
        default: "yes"
        description: Whether the data is from a strand-specific assay. 'reverse' means 'yes' with reversed strand interpretation.
        info:
          orig_arg: --stranded
      - name: --minimum_alignment_quality
        type: integer
        alternatives: [-a, --minaqual]
        default: 10
        description: |
          Skip all reads with MAPQ alignment quality lower than the given minimum value. 
          MAPQ is the 5th column of a SAM/BAM file and its usage depends on the software 
          used to map the reads.
        info:
          orig_arg: --minaqual
      - name: --type
        type: string
        alternatives: [-t]
        example: exon
        description: "Feature type (3rd column in GTF file) to be used, all features of other type are ignored (default, suitable for Ensembl GTF files: exon)"
        info:
          orig_arg: --type
      - name: --id_attribute
        type: string
        alternatives: [-i]
        example: gene_id
        description: |
          GTF attribute to be used as feature ID (default, suitable for Ensembl GTF files: gene_id).
          All feature of the right type (see -t option) within the same GTF attribute will be added
          together. The typical way of using this option is to count all exonic reads from each gene
          and add the exons but other uses are possible as well. You can call this option multiple
          times: in that case, the combination of all attributes separated by colons (:) will be used
          as a unique identifier, e.g. for exons you might use -i gene_id -i exon_number.
        multiple: true
        info:
          orig_arg: --idattr
      - name: --additional_attributes
        type: string
        example: gene_name
        description: |
          Additional feature attributes (suitable for Ensembl GTF files: gene_name). Use multiple times
          for more than one additional attribute. These attributes are only used as annotations in the
          output, while the determination of how the counts are added together is done based on option -i.
        multiple: true
        info:
          orig_arg: --additional-attr
      - name: --add_chromosome_info
        type: boolean_true
        description: |
          Store information about the chromosome of each feature as an additional attribute
          (e.g. colunm in the TSV output file).
        info:
          orig_arg: --add-chromosome-info
      - name: --mode
        type: string
        alternatives: [-m]
        choices: [union, intersection-strict, intersection-nonempty]
        default: union
        description: Mode to handle reads overlapping more than one feature.
        info:
          orig_arg: --mode
      - name: --non_unique
        type: string
        choices: [none, all, fraction, random]
        default: none
        description: Whether and how to score reads that are not uniquely aligned or ambiguously assigned to features.
        info:
          orig_arg: --nonunique
      - name: --secondary_alignments
        type: string
        choices: [score, ignore]
        description: Whether to score secondary alignments (0x100 flag).
        info:
          orig_arg: --secondary-alignments
      - name: --supplementary_alignments
        type: string
        choices: [score, ignore]
        description: Whether to score supplementary alignments (0x800 flag).
        info:
          orig_arg: --supplementary-alignments
      - name: --counts_output_sparse
        type: boolean_true
        description: Store the counts as a sparse matrix (mtx, h5ad, loom).
        info:
          orig_arg: --counts-output-sparse
resources:
  - type: python_script
    path: script.py
test_resources:
  - type: python_script
    path: test.py
  - path: /resources_test/cellranger_tiny_fastq

engines:
- type: docker
  image: python:3.12-slim
  setup:
    - type: apt
      packages: 
        - procps
    - type: python
      packages:
        - HTSeq
        - pyyaml
        - scipy
        - pandas

runners:
- type: executable
- type: nextflow
  directives:
    label: [ highmem, highcpu, middisk ]
