name: bedtools_merge
namespace: bedtools
description: |
  Merges overlapping BED/GFF/VCF entries into single intervals.
  
  This tool combines overlapping or book-ended features in BED, GFF, or VCF
  files into single merged intervals. It provides extensive options for
  controlling merge behavior, including strand-specific merging, distance
  thresholds, and aggregation operations on additional columns.
  
  **Default behavior:** Merges overlapping and adjacent features regardless of strand
  **Input requirements:** Input file must be sorted by chromosome and start position

keywords: [Merge, Overlapping, BED, GFF, VCF, Intervals]
links:
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/merge.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 file in BED, GFF, or VCF format to be merged.
          
          **Requirements:**
          - File must be sorted by chromosome and start position
          - Use `bedtools sort` if input is not sorted
          
          **Supported formats:** BED, GFF, VCF, or BAM (with --bed flag)
        required: true
        example: intervals.bed
    
  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: |
          Output file containing merged intervals.
          
          The output will contain merged intervals in BED format, with
          additional columns included if aggregation operations are specified
          via --columns and --operation parameters.
        required: true
        example: merged_intervals.bed

  - name: Options
    arguments:
      - name: --strand
        alternatives: [-s]
        type: boolean_true
        description: |
          Force strandedness for merging operations.
          
          Only merge features that are on the same strand. Features on
          opposite strands will be treated as separate and not merged,
          even if they overlap.
          
          **Default:** Merging ignores strand information

      - name: --specific_strand
        alternatives: [-S]
        type: string
        choices: ["+", "-"]
        description: |
          Merge features from one specific strand only.
          
          **Options:**
          - "+" : Merge only forward strand features
          - "-" : Merge only reverse strand features
          
          Features from the opposite strand will be ignored entirely.
        example: "+"

      - name: --distance
        alternatives: [-d]
        type: integer
        description: |
          Maximum distance between features for merging.
          
          **Positive values:** Features within this distance will be merged
          **Negative values:** Minimum overlap required (in base pairs)
          **Zero (default):** Only overlapping and book-ended features merge
          
          **Examples:**
          - `-d 100` : Merge features within 100bp of each other
          - `-d -50` : Require at least 50bp overlap to merge
        default: 0
        example: 100

      - name: --columns
        alternatives: [-c]
        type: string
        description: |
          Columns to aggregate during merging operations.
          
          Specify which columns from the input file should be included
          in the merged output with aggregation operations applied.
          
          **Format:** Single column (e.g., "5") or comma-separated list (e.g., "4,5,6")
          **Column numbering:** 1-indexed (column 1 = chromosome, etc.)
        example: "4,5,6"

      - name: --operation
        alternatives: [-o]
        type: string
        description: |
          Aggregation operations to apply to specified columns.
          
          **Numerical operations:**
          - sum, min, max, mean, median, mode
          - absmin, absmax, stdev, sstdev
          
          **List operations:**
          - collapse (comma-separated list with duplicates)
          - distinct (comma-separated unique values)
          - distinct_sort_num (unique values, numerically sorted)
          
          **Count operations:**
          - count (number of values)
          - count_distinct (number of unique values)
          
          **Positional operations:**
          - first (first value), last (last value)
          
          **Multiple operations:** Use comma-separated list (e.g., "sum,mean,count")
        example: "mean,count"
      
      - name: --delimiter
        alternatives: [-delim]
        type: string
        description: |
          Custom delimiter for collapse/distinct operations.
          
          Character or string used to separate values in list-type
          operations like collapse, distinct, etc.
        default: ","
        example: "|"

      - name: --precision
        alternatives: [-prec]
        type: integer
        description: |
          Decimal precision for numerical output values.
          
          Controls the number of decimal places displayed for
          floating-point results from numerical operations.
        default: 5
        example: 3

      - name: --bed
        type: boolean_true
        description: |
          Output in BED format when using BAM input.
          
          When the input file is in BAM format, this flag ensures
          the output is written in standard BED format instead of
          the default BAM-specific output format.

      - name: --header
        type: boolean_true
        description: |
          Include header from input file in output.
          
          Preserves and prints any header lines from the input file
          (e.g., GFF version lines, VCF headers) before the merged results.

      - name: --no_buffer
        alternatives: [-nobuf]
        type: boolean_true
        description: |
          Disable buffered output for real-time processing.
          
          **Default behavior:** Output is buffered for efficiency
          **With --no_buffer:** Each line printed immediately as generated
          
          **Use cases:** Real-time processing, piping to other tools
          **Performance:** Slower for large files but enables streaming

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