name: bedtools_map
namespace: bedtools

description: |
  Apply statistical functions to columns from overlapping genomic intervals.
  
  This tool maps values from intervals in file B onto overlapping intervals in file A
  by applying statistical operations (sum, mean, median, etc.). For each interval in A,
  it finds all overlapping intervals in B and applies the specified function to the 
  specified column(s). Useful for aggregating scores, computing statistics over 
  genomic regions, or annotating intervals with quantitative data.

keywords: [genomics, intervals, map, statistics, aggregate, annotate, overlap, scores]
links:
  homepage: https://bedtools.readthedocs.io/
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/map.html
  repository: https://github.com/arq5x/bedtools2
references:
  doi: 10.1093/bioinformatics/btq033
license: MIT

requirements:
  commands: [bedtools]

authors:
  - __merge__: /src/_authors/robrecht_cannoodt.yaml
    roles: [author, maintainer]

argument_groups:
  - name: Inputs
    arguments:
      - name: --input_a
        alternatives: [-a]
        type: file
        description: |
          First input file (intervals to annotate).
          
          **Format:** BED, GFF, VCF file with genomic intervals
          **Requirement:** Must be sorted by chromosome, then start position
          **Usage:** Each interval will be annotated with mapped values from file B
        required: true
        example: target_regions.bed
      
      - name: --input_b
        alternatives: [-b]
        type: file
        description: |
          Second input file (source of values to map).
          
          **Format:** BED, GFF, VCF file with genomic intervals and data columns
          **Requirement:** Must be sorted by chromosome, then start position
          **Usage:** Overlapping intervals provide values for mapping operations
        required: true
        example: data_intervals.bed

  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: |
          Output file with mapped values appended to input A intervals.
          
          **Format:** Same as input A with additional columns for mapped values
          **Content:** Original columns from A plus computed statistical values
          **Order:** Follows the order specified in column and operation parameters
        required: true
        example: annotated_regions.bed

  - name: Mapping Options
    arguments:
      - name: --columns
        alternatives: [-c]
        type: string
        description: |
          Columns from file B to use for mapping operations.
          
          **Default:** 5 (fifth column, typically score column in BED)
          **Format:** Comma-delimited list for multiple columns
          **Example:** "5" for score column, "4,5" for name and score columns
          **Indexing:** 1-based column numbering
        example: "5"
        
      - name: --operations
        alternatives: [-o]
        type: string
        description: |
          Statistical operations to apply to specified columns.
          
          **Numeric operations:** sum, min, max, absmin, absmax, mean, median, mode, antimode, stdev, sstdev, count, count_distinct
          **List operations:** collapse, distinct, distinct_sort_num, distinct_sort_num_desc, distinct_only
          **Position operations:** first, last
          
          **Default:** sum
          **Format:** Comma-delimited list for multiple operations
          **Pairing:** Operations applied to columns in respective order
        example: "mean"
        
      - name: --delimiter
        alternatives: [-delim]
        type: string
        description: |
          Custom delimiter for collapse operations.
          
          **Default:** "," (comma)
          **Usage:** Only affects collapse, distinct, and related operations
          **Example:** "|" for pipe-separated values, ";" for semicolon-separated
        example: "|"
        
      - name: --precision
        alternatives: [-prec]
        type: integer
        description: |
          Decimal precision for numerical output.
          
          **Default:** 5 decimal places
          **Range:** 0-15 (reasonable range for floating point precision)
          **Usage:** Controls rounding of computed statistical values
        example: 3

  - name: Overlap Options
    arguments:
      - name: --min_overlap_a
        alternatives: [-f]
        type: double
        description: |
          Minimum overlap required as fraction of A.
          
          **Range:** 0.0 to 1.0
          **Default:** 1E-9 (effectively 1bp)
          **Example:** 0.50 requires 50% of A to be overlapped by B
        example: 0.5
        
      - name: --min_overlap_b
        alternatives: [-F]
        type: double
        description: |
          Minimum overlap required as fraction of B.
          
          **Range:** 0.0 to 1.0
          **Default:** 1E-9 (effectively 1bp)
          **Example:** 0.50 requires 50% of B to overlap A
        example: 0.5
        
      - name: --reciprocal
        alternatives: [-r]
        type: boolean_true
        description: |
          Require reciprocal overlap for both A and B.
          
          **Effect:** Both -f and -F thresholds must be satisfied
          **Example:** With -f 0.90 -r, requires B overlaps 90% of A AND A overlaps 90% of B
          **Default:** false
          
      - name: --either
        alternatives: [-e]
        type: boolean_true
        description: |
          Require minimum fraction satisfied for A OR B.
          
          **Effect:** Only one of -f or -F thresholds needs to be satisfied
          **Alternative:** Without -e, both fractions must be satisfied
          **Default:** false (both required)

  - name: Strand Options
    arguments:
      - name: --same_strand
        alternatives: [-s]
        type: boolean_true
        description: |
          Require same strandedness for overlaps.
          
          **Effect:** Only consider overlaps on the same strand
          **Default:** false (strand-independent)
          
      - name: --opposite_strand
        alternatives: [-S]
        type: boolean_true
        description: |
          Require different strandedness for overlaps.
          
          **Effect:** Only consider overlaps on opposite strands
          **Default:** false (strand-independent)
          **Note:** May have issues in some bedtools versions

  - name: Format Options
    arguments:
      - name: --split
        type: boolean_true
        description: |
          Treat split BAM or BED12 entries as distinct intervals.
          
          **Effect:** Split multi-block entries into individual intervals
          **Usage:** For BAM alignments with gaps or BED12 entries
          **Default:** false
          
      - name: --bed_output
        alternatives: [--bed]
        type: boolean_true
        description: |
          Write output in BED format when using BAM input.
          
          **Effect:** Forces BED output format for BAM inputs
          **Default:** false
          
      - name: --header
        type: boolean_true
        description: |
          Print header from file A prior to results.
          
          **Effect:** Includes original header from input file A
          **Default:** false

  - name: Advanced Options
    arguments:
      - name: --genome
        alternatives: [-g]
        type: file
        description: |
          Genome file for consistent chromosome sorting.
          
          **Format:** Tab-delimited file with chromosome name and size
          **Usage:** Only applies when used with sorted data
          **Purpose:** Enforces consistent chromosome sort order
        example: genome.txt
        
      - name: --no_name_check
        alternatives: [--nonamecheck]
        type: boolean_true
        description: |
          Skip chromosome naming convention checks for sorted data.
          
          **Effect:** Allows different naming (e.g., "chr1" vs "chr01")
          **Usage:** For files with inconsistent chromosome naming
          **Default:** false (strict checking)
          
      - name: --no_buffer
        alternatives: [--nobuf]
        type: boolean_true
        description: |
          Disable buffered output.
          
          **Effect:** Print each line immediately instead of buffering
          **Usage:** For real-time processing or piping
          **Trade-off:** Slower performance but immediate output
          **Default:** false (buffered output)
          
      - name: --io_buffer
        alternatives: [--iobuf]
        type: string
        description: |
          Specify input buffer memory size.
          
          **Format:** Integer with optional K/M/G suffix
          **Example:** "128M" for 128 megabytes
          **Note:** No effect with compressed files
        example: "128M"

resources:
  - type: bash_script
    path: script.sh
test_resources:
  - type: bash_script
    path: test.sh
  - 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
