name: bedtools_flank
namespace: bedtools

description: |
  Create flanking intervals for each genomic feature.
  
  This tool generates new intervals representing the regions immediately 
  upstream and/or downstream of existing genomic features. Unlike slop which
  extends existing intervals, flank creates entirely new intervals from the
  flanking regions.

keywords: [genomics, intervals, flank, upstream, downstream, flanking, regions]
links:
  homepage: https://bedtools.readthedocs.io/
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/flank.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
        alternatives: [-i]
        type: file
        description: |
          Input file with genomic intervals.
          
          **Format:** BED, GFF, VCF file with genomic intervals
          **Usage:** Features for which flanking regions will be created
        required: true
        example: intervals.bed
        
      - name: --genome
        alternatives: [-g]
        type: file
        description: |
          Genome file defining chromosome sizes.
          
          **Format:** Tab-delimited file with chromosome name and size
          **Purpose:** Prevents flanks from extending beyond chromosome boundaries
          **Example:** chr1\t249250621
          **Tip:** Can use samtools faidx output (.fai file)
        required: true
        example: genome.txt

  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: |
          Output file with flanking intervals.
          
          Contains new intervals representing the flanking regions
          of the input features.
        required: true
        example: flanking_regions.bed

  - name: Flanking Options
    arguments:
      - name: --both
        alternatives: [-b]
        type: string
        description: |
          Create flanking intervals using specified distance in both directions.
          
          **Input:** Integer (base pairs) or Float (if used with --pct)
          **Effect:** Creates flanks of equal size upstream and downstream
          **Example:** "1000" creates 1kb flanks on both sides
          **Mutually exclusive:** Cannot use with --left or --right
        example: "1000"
        
      - name: --left
        alternatives: [-l]
        type: string
        description: |
          Distance for left/upstream flank from original start coordinate.
          
          **Input:** Integer (base pairs) or Float (if used with --pct)
          **Strand-aware:** When used with --strand, respects feature orientation
          **Example:** "500" creates 500bp upstream flank
          **Requires:** Must be used together with --right
        example: "500"
        
      - name: --right
        alternatives: [-r]
        type: string
        description: |
          Distance for right/downstream flank from original end coordinate.
          
          **Input:** Integer (base pairs) or Float (if used with --pct)
          **Strand-aware:** When used with --strand, respects feature orientation
          **Example:** "300" creates 300bp downstream flank  
          **Requires:** Must be used together with --left
        example: "300"

  - name: Flanking Behavior
    arguments:
      - name: --strand
        alternatives: [-s]
        type: boolean_true
        description: |
          Define left and right flanks based on strand orientation.
          
          **Effect:** For negative-strand features, left becomes downstream
          **Example:** -l 500 on minus strand starts flank 500bp downstream
          **Default:** false (ignore strand)
          
      - name: --percent
        alternatives: [-pct]
        type: boolean_true
        description: |
          Define flanking distances as fraction of feature length.
          
          **Effect:** Distances become proportional to feature size
          **Example:** -l 0.5 on 1000bp feature creates 500bp upstream flank
          **Input format:** Use decimals (e.g., "0.1" for 10%)
          **Default:** false (absolute base pairs)

  - name: Output Options
    arguments:
      - name: --header
        type: boolean_true
        description: |
          Print header from input file prior to results.
          
          **Effect:** Preserves original file header in output
          **Default:** false

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
