name: bedtools_tag
namespace: bedtools
description: |
  Annotate BAM alignments with tags based on overlaps with genomic intervals.
  
  bedtools tag reads alignments from a BAM file and annotates them with custom tags 
  based on their overlap with intervals from one or more BED/GFF/VCF files. Each 
  alignment that overlaps with an interval receives a tag in the BAM record, making 
  this tool essential for marking reads that overlap with specific genomic features 
  like genes, enhancers, or repetitive elements.
  
  This tool is commonly used for:
  - Tagging reads that overlap with specific genomic features
  - Annotating alignments with gene names or functional regions
  - Marking reads for downstream filtering based on overlap patterns
  - Quality control by identifying reads in problematic regions
  - Single-cell RNA-seq analysis for feature assignment
  - ChIP-seq analysis for peak annotation and read classification

keywords: [genomics, bam, annotation, tagging, overlap, alignment, features]
links:
  homepage: https://bedtools.readthedocs.io/en/latest/content/tools/tag.html
  documentation: https://bedtools.readthedocs.io/en/latest/content/tools/tag.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
        alternatives: [-i]
        type: file
        description: |
          Input BAM file to annotate with tags.
          
          **Format:** BAM file with aligned sequencing reads
          **Content:** Alignments that will be tagged based on overlaps
          **Requirements:** Must be a valid BAM file (indexed .bai file recommended)
          **Usage:** Each alignment overlapping with annotation files will receive tags
          **Output:** Tagged BAM file with additional tag fields
        required: true
        example: alignments.bam

      - name: --files
        type: file
        multiple: true
        description: |
          BED/GFF/VCF annotation files for tagging overlapping alignments.
          
          **Format:** BED, GFF, or VCF files with genomic intervals
          **Content:** Genomic features used for alignment annotation
          **Usage:** Alignments overlapping these intervals receive tags
          **Multiple files:** Each file can have its own label for distinction
          **Requirements:** Files should have consistent chromosome naming with BAM
        required: true
        example: ["genes.bed", "enhancers.bed", "repeats.bed"]

      - name: --labels
        type: string
        multiple: true
        description: |
          Labels corresponding to each annotation file.
          
          **Format:** String labels for each annotation file
          **Usage:** Must provide one label per annotation file in --files
          **Content:** These labels will be used as tag values in the BAM output
          **Order:** Must match the order of files in --files parameter
          **Applications:** Distinguish overlaps from different annotation sources
          **Note:** Required unless --use_names, --use_scores, or --use_intervals is specified
        required: false
        example: ["GENE", "ENHANCER", "REPEAT"]

  - name: Outputs
    arguments:
      - name: --output
        type: file
        description: |
          Output BAM file with tagged alignments.
          
          **Format:** BAM file with original alignments plus overlap tags
          **Content:** All original alignment data plus custom tags for overlaps
          **Tags:** Alignments overlapping annotation files receive additional tag fields
          **Preservation:** Non-overlapping alignments remain unchanged
          **Indexing:** Output can be indexed like any standard BAM file
        required: true
        direction: output
        example: tagged_alignments.bam

  - name: Overlap Options
    arguments:
      - name: --min_overlap
        alternatives: [-f]
        type: double
        description: |
          Minimum overlap required as a fraction of the alignment.
          
          **Default:** 1E-9 (essentially 1 base pair)
          **Range:** 0.0 to 1.0
          **Usage:** Alignment must overlap at least this fraction of its length
          **Example:** 0.5 requires alignment to overlap 50% of its length with feature
          **Applications:** Filter spurious overlaps, require substantial overlap
        example: 0.1

  - name: Strand Options
    arguments:
      - name: --same_strand
        alternatives: [-s]
        type: boolean_true
        description: |
          Require overlaps on the same strand.
          
          **Usage:** Only tag alignments that overlap features on the same strand
          **Applications:** Strand-specific RNA-seq analysis, sense transcript tagging
          **Default:** false (overlaps reported without respect to strand)
          **Interaction:** Mutually exclusive with --opposite_strand

      - name: --opposite_strand
        alternatives: [-S]
        type: boolean_true
        description: |
          Require overlaps on the opposite strand.
          
          **Usage:** Only tag alignments that overlap features on the opposite strand
          **Applications:** Antisense transcript detection, strand-specific filtering
          **Default:** false (overlaps reported without respect to strand)
          **Interaction:** Mutually exclusive with --same_strand

  - name: Tag Options
    arguments:
      - name: --tag_name
        alternatives: [-tag]
        type: string
        description: |
          Specify the BAM tag name to use for annotations.
          
          **Default:** "YB" 
          **Format:** Two-character string (standard BAM tag format)
          **Usage:** Custom tag name for storing overlap information
          **Examples:** "YK", "ZZ", "XG"
          **Standards:** Follow BAM tag naming conventions
        example: YK

      - name: --use_names
        alternatives: [-names]
        type: boolean_true
        description: |
          Use the name field from annotation files to populate tags.
          
          **Usage:** Instead of labels, use the name column from BED/GFF files
          **Applications:** Gene name tagging, feature-specific annotation
          **Requirements:** Annotation files must have name fields (4th column in BED)
          **Default:** false (uses --labels values instead)

      - name: --use_scores
        alternatives: [-scores]
        type: boolean_true
        description: |
          Use the score field from annotation files to populate tags.
          
          **Usage:** Instead of labels, use the score column from annotation files
          **Applications:** Confidence scoring, quantitative tagging
          **Requirements:** Annotation files must have score fields (5th column in BED)
          **Default:** false (uses --labels values instead)

      - name: --use_intervals
        alternatives: [-intervals]
        type: boolean_true
        description: |
          Use full interval information to populate tags.
          
          **Content:** Include interval coordinates, name, score, and strand in tags
          **Format:** Full genomic interval description as tag value
          **Applications:** Detailed annotation tracking, interval provenance
          **Requirements:** Still requires --labels to identify source files
          **Default:** false (uses --labels values instead)

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
