name: bedtools_bamtobed
namespace: bedtools
description: |
  Converts BAM alignments to BED6 or BEDPE format.
  
  This tool converts alignments in BAM format to either BED6 or BEDPE format,
  allowing for flexible downstream analysis of genomic intervals.
keywords: [Converts, BAM, BED, BED6, BEDPE]
links:
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/bamtobed.html
  repository: https://github.com/arq5x/bedtools2
  homepage: https://bedtools.readthedocs.io/en/latest/
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
        description: |
          Input BAM file containing aligned sequences.
          
          **Requirements:**
          - Must be in SAM/BAM format
          - For paired-end BEDPE output (`--bedpe`), must be grouped or sorted by query name
        required: true
        example: input.bam
    
  - name: Outputs
    arguments:
      - name: --output
        alternatives: [-o]
        required: true
        type: file
        direction: output
        description: |
          Output file in BED or BEDPE format.
          
          **Output formats:**
          - Default: BED6 format (6 columns)
          - With `--bedpe`: BEDPE format for paired-end data
          - With `--bed12`: BED12 format with blocked intervals
        example: output.bed

  - name: Options
    arguments:
      - name: --bedpe
        type: boolean_true
        description: | 
          Write BEDPE format for paired-end data.
          
          **Requirements:**
          - BAM must be grouped or sorted by query name
          - Produces paired-end BED format with mate information
      
      - name: --mate1
        type: boolean_true
        description: | 
          When writing BEDPE format (`--bedpe`), always report mate one as the first BEDPE block.
          
          Ensures consistent ordering of paired-end reads in output.
      
      - name: --bed12
        type: boolean_true
        description: | 
          Write blocked BED format (BED12 format).
          
          **Features:**
          - Creates 12-column BED format with block information
          - Automatically forces `--split` option
          - Useful for representing spliced alignments
          
          See [BED12 format specification](http://genome-test.cse.ucsc.edu/FAQ/FAQformat#format1) for details.

      - name: --split
        type: boolean_true
        description: | 
          Report split BAM alignments as separate BED entries.
          
          **Behavior:**
          - Splits only on **N** CIGAR operations (introns/gaps)
          - Each split becomes a separate BED interval
          - Useful for RNA-seq data with spliced alignments

      - name: --splitD
        type: boolean_true
        description: | 
          Split alignments based on both **N** and **D** CIGAR operators.
          
          **Features:**
          - Splits on N (gaps/introns) and D (deletions) operations
          - Automatically forces `--split` option
          - More aggressive splitting than `--split` alone

      - name: --edit_distance
        alternatives: [-ed]
        type: boolean_true
        description: | 
          Use BAM edit distance (NM tag) for BED score instead of mapping quality.
          
          **Scoring behavior:**
          - **Default BED**: Uses mapping quality as score
          - **Default BEDPE**: Uses minimum of two mapping qualities
          - **With --ed + --bedpe**: Reports total edit distance from both mates

      - name: --tag
        type: string
        description: | 
          Use other numeric BAM alignment tag for BED score.
          
          **Usage:**
          - Specify any numeric BAM tag (e.g., `SM`, `AS`, `XS`)
          - Replaces default mapping quality scoring
          - **Not allowed** with BEDPE output format
        example: "SM"
      
      - name: --color
        type: string
        description: | 
          RGB color string for BED12 format visualization.
          
          **Format:** R,G,B values (0-255 each)
          
          **Default:** `255,0,0` (red)
        example: "255,0,0"

      - name: --cigar
        type: boolean_true
        description: | 
          Add the CIGAR string as a 7th column in BED output.
          
          Useful for preserving alignment information in BED format.

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