name: bedtools_fisher
namespace: bedtools

description: |
  Calculate Fisher's exact test statistic between two feature files.
  
  This tool performs Fisher's exact test to assess the statistical significance
  of overlaps between genomic intervals in two files. It calculates the probability
  of observing the given overlap pattern by chance, providing a p-value for 
  statistical inference.

keywords: [genomics, intervals, fisher, statistics, overlap, significance, test]
links:
  homepage: https://bedtools.readthedocs.io/
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/fisher.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]

argument_groups:
  - name: Inputs
    arguments:
      - name: --input_a
        alternatives: [-a]
        type: file
        description: |
          First input file for comparison.
          
          **Format:** BED, GFF, VCF file with genomic intervals
          **Requirement:** Must be sorted by chromosome, then start position
          **Usage:** File A for Fisher's exact test comparison
        required: true
        example: intervals_a.bed
      
      - name: --input_b
        alternatives: [-b]
        type: file
        description: |
          Second input file for comparison.
          
          **Format:** BED, GFF, VCF file with genomic intervals
          **Requirement:** Must be sorted by chromosome, then start position
          **Usage:** File B for Fisher's exact test comparison
        required: true
        example: intervals_b.bed
        
      - name: --genome
        alternatives: [-g]
        type: file
        description: |
          Genome file defining chromosome sizes.
          
          **Format:** Tab-delimited file with chromosome name and size
          **Purpose:** Enforces consistent chromosome sort order
          **Example:** chr1\t249250621
        required: true
        example: genome.txt

  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: |
          Output file with Fisher's exact test results.
          
          Contains statistical results including p-values for overlap
          significance between input files.
        required: true
        example: fisher_results.txt

  - name: Overlap Options
    arguments:
      - name: --merge_overlaps
        alternatives: [-m]
        type: boolean_true
        description: |
          Merge overlapping intervals before analysis.
          
          **Effect:** Collapses overlapping intervals in both files
          **Usage:** Prevents double-counting of overlapping features
          **Default:** false (no merging)
        
      - 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
        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 be overlapped
        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 report 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 report overlaps on opposite strands
          **Default:** false (strand-independent)

  - 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: --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
