name: bedtools_igv
namespace: bedtools

description: |
  Create IGV batch script to generate automated screenshots of genomic regions.
  
  This tool generates a batch script that can be run within IGV (Integrative Genomics Viewer)
  to automatically create image snapshots at each interval defined in a BED/GFF/VCF file.
  Useful for creating automated visualizations of genomic features or regions of interest.

keywords: [genomics, visualization, igv, screenshots, batch, automation, intervals]
links:
  homepage: https://bedtools.readthedocs.io/
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/igv.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 for visualization.
          
          **Format:** BED, GFF, or VCF file with genomic regions
          **Usage:** Each interval will generate one IGV screenshot
          **Column 4:** Optional name field used for image filenames (with --use_name)
        required: true
        example: regions_of_interest.bed

  - name: Outputs
    arguments:
      - name: --output
        type: file
        direction: output
        description: |
          Output IGV batch script file.
          
          **Format:** Plain text script with IGV commands
          **Usage:** Run this script within IGV to generate automated screenshots
          **Extension:** Typically .txt or .igv
        required: true
        example: igv_batch_script.txt

  - name: Output Configuration
    arguments:
      - name: --output_path
        alternatives: [--path]
        type: string
        description: |
          Full path where IGV snapshots should be written.
          
          **Format:** Directory path (must exist before running script)
          **Default:** Current directory (./)
          **Example:** "/path/to/igv/images/"
          **Note:** Include trailing slash for directories
        example: "./igv_images/"
        
      - name: --image_format
        alternatives: [--img]
        type: string
        description: |
          Image format for generated screenshots.
          
          **Options:** png, eps, svg
          **Default:** png
          **Recommendation:** PNG for most use cases
        choices: [png, eps, svg]
        example: "png"

  - name: IGV Session Options
    arguments:
      - name: --session_file
        alternatives: [--sess]
        type: file
        description: |
          Path to existing IGV session file to load before taking snapshots.
          
          **Format:** IGV session file (.xml)
          **Purpose:** Pre-loads genome, tracks, and display settings
          **Optional:** If not provided, assumes genome and tracks are already loaded
        example: "my_analysis.xml"

  - name: Display Options
    arguments:
      - name: --sort_reads
        alternatives: [--sort]
        type: string
        description: |
          BAM read sorting method to apply for each image.
          
          **Options:** base, position, strand, quality, sample, readGroup
          **Default:** No sorting applied
          **Usage:** Only relevant when BAM tracks are loaded in IGV
        choices: [base, position, strand, quality, sample, readGroup]
        example: "position"
        
      - name: --collapse_reads
        alternatives: [--clps]
        type: boolean_true
        description: |
          Collapse aligned reads before taking snapshots.
          
          **Effect:** Shows read coverage instead of individual reads
          **Usage:** Useful for high-coverage regions
          **Default:** false (show individual reads)
          
      - name: --flank_size
        alternatives: [--slop]
        type: integer
        description: |
          Number of flanking base pairs on left and right of each region.
          
          **Range:** 0 or positive integer
          **Default:** 0 (no flanking)
          **Purpose:** Include context around regions of interest
          **Example:** 1000 adds 1kb padding on each side
        example: 1000
        
      - name: --use_name
        alternatives: [--name]
        type: boolean_true
        description: |
          Use the name field (column 4) from input file for image filenames.
          
          **Effect:** Images named using BED name field instead of coordinates
          **Default:** false (use "chr:start-end.ext" format)
          **Requirement:** Input file must have name field (column 4)

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
