name: bedtools_genomecov
namespace: bedtools
description: |
  Compute the coverage of a feature file among a genome.
  
  Calculates genome-wide coverage statistics from BED, GFF, VCF, or BAM files.
  Can produce coverage histograms, per-base depth, or BedGraph format output.
keywords: [genome coverage, BED, GFF, VCF, BAM, depth, histogram, bedgraph]
links:
  homepage: https://bedtools.readthedocs.io/en/latest/
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/genomecov.html
  repository: https://github.com/arq5x/bedtools2
references:
  doi: 10.1093/bioinformatics/btq033
license: MIT
requirements:
  commands: [bedtools]
authors:
  - __merge__: /src/_authors/theodoro_gasperin.yaml
    roles: [author]
  - __merge__: /src/_authors/robrecht_cannoodt.yaml
    roles: [author, maintainer]

argument_groups:
  - name: Inputs
    arguments:
      - name: --input
        alternatives: [-i]
        type: file
        direction: input
        description: |
          Input genomic intervals file in BED, GFF, or VCF format.
          
          **Supported formats:**
          - BED format (standard genomic intervals)
          - GFF/GTF format (gene annotations)
          - VCF format (variant calls)
          
          **Note:** Required when not using `--input_bam`
        example: input.bed
      
      - name: --input_bam
        alternatives: [-ibam]
        type: file
        description: |
          Input BAM file for coverage calculation.
          
          **Requirements:**
          - BAM file must be sorted by position
          - When using BAM input, `--genome` option is ignored
          - Coordinates are determined from BAM header
        example: input.bam

      - name: --genome
        alternatives: [-g]
        type: file
        direction: input
        description: |
          Genome file defining chromosome names and sizes.
          
          **Format:** Two-column tab-delimited file:
          ```
          chr1    248956422
          chr2    242193529
          ```
          
          **Note:** Required when using `--input`, ignored when using `--input_bam`
        example: genome.txt
    
  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: | 
          Output file containing coverage information.
          
          **Output formats depend on options:**
          - **Default:** Coverage histogram (depth vs count)
          - **With `--depth`:** Per-base depth (1-based coordinates)
          - **With `--bed_graph`:** BedGraph format for genome browsers
        required: true
        example: coverage.txt
  
  - name: Options
    arguments:

      - name: --depth
        alternatives: [-d]
        type: boolean_true
        description: |
          Report the depth at each genome position with 1-based coordinates.
          
          **Output format:** `chromosome position depth`
          
          **Default behavior:** Reports coverage histogram instead

      - name: --depth_zero
        alternatives: [-dz]
        type: boolean_true
        description: |
          Report depth at each genome position with 0-based coordinates.
          
          **Features:**
          - Only reports positions with non-zero coverage
          - Uses 0-based coordinate system
          - More memory efficient than `--depth`

      - name: --bed_graph
        alternatives: [-bg]
        type: boolean_true
        description: |
          Report depth in BedGraph format for genome browser visualization.
          
          **Output format:** `chromosome start end depth`
          
          See [BedGraph specification](https://genome.ucsc.edu/goldenPath/help/bedgraph.html) for details.

      - name: --bed_graph_zero_coverage
        alternatives: [-bga]
        type: boolean_true
        description: |
          Report depth in BedGraph format including zero-coverage regions.
          
          **Features:**
          - Same as `--bed_graph` but includes regions with 0 coverage
          - Useful for finding uncovered regions: `grep -w 0$ output.bg`
          - Generates larger output files

      - name: --split
        type: boolean_true
        description: |
          Treat "split" BAM or BED12 entries as distinct BED intervals.
          when computing coverage.
          For BAM files, this uses the CIGAR "N" and "D" operations 
          to infer the blocks for computing coverage.
          For BED12 files, this uses the BlockCount, BlockStarts, and BlockEnds
          fields (i.e., columns 10,11,12).

      - name: --ignore_deletion
        alternatives: -ignoreD
        type: boolean_true
        description: |
          Ignore local deletions (CIGAR "D" operations) in BAM entries
          when computing coverage.

      - name: --strand
        type: string
        choices: ["+", "-"]
        description: |
          Calculate coverage of intervals from a specific strand.
          With BED files, requires at least 6 columns (strand is column 6). 

      - name: --pair_end_coverage
        alternatives: -pc
        type: boolean_true
        description: |
          Calculate coverage of pair-end fragments.
          Works for BAM files only

      - name: --fragment_size
        alternatives: -fs
        type: boolean_true
        description: |
          Force to use provided fragment size instead of read length
          Works for BAM files only

      - name: --du
        type: boolean_true
        description: |
          Change strand af the mate read (so both reads from the same strand) useful for strand specific
          Works for BAM files only

      - name: --five_prime
        alternatives: ["-5"]
        type: boolean_true
        description: |
          Calculate coverage of 5" positions (instead of entire interval).

      - name: --three_prime
        alternatives: ["-3"]
        type: boolean_true
        description: |
          Calculate coverage of 3" positions (instead of entire interval).

      - name: --max
        type: integer
        min: 0
        description: |
          Combine all positions with a depth >= max into
          a single bin in the histogram. Irrelevant
          for -d and -bedGraph
          - (INTEGER)

      - name: --scale
        type: double
        min: 0
        description: |
          Scale the coverage by a constant factor.
          Each coverage value is multiplied by this factor before being reported.
          Useful for normalizing coverage by, e.g., reads per million (RPM).
          - Default is 1.0; i.e., unscaled.
          - (FLOAT)

      - name: --trackline
        type: boolean_true
        description: |
          Adds a UCSC/Genome-Browser track line definition in the first line of the output.
          - See here for more details about track line definition:
                http://genome.ucsc.edu/goldenPath/help/bedgraph.html
          - NOTE: When adding a trackline definition, the output BedGraph can be easily
                uploaded to the Genome Browser as a custom track,
                BUT CAN NOT be converted into a BigWig file (w/o removing the first line).
      
      - name: --trackopts
        type: string
        description: |
          Writes additional track line definition parameters in the first line.
          - Example:
            -trackopts 'name="My Track" visibility=2 color=255,30,30'
            Note the use of single-quotes if you have spaces in your parameters.
          - (TEXT)
        multiple: true

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/bedtools:2.31.1--h13024bc_3
    setup:
      - type: docker
        run:
          - "bedtools --version 2>&1 | head -1 | sed 's/.*bedtools v/bedtools: /' > /var/software_versions.txt"

runners:
  - type: executable
  - type: nextflow