name: bcftools_norm
namespace: bcftools
description: | 
  Left-align and normalize indels, check if REF alleles match the reference, split multiallelic sites into multiple rows; 
  recover multiallelics from multiple rows. 
keywords: [Normalize, VCF, BCF]
links:
  homepage: https://samtools.github.io/bcftools/
  documentation: https://samtools.github.io/bcftools/bcftools.html#norm
  repository: https://github.com/samtools/bcftools
  issue_tracker: https://github.com/samtools/bcftools/issues
references:
  doi: https://doi.org/10.1093/gigascience/giab008
license: MIT/Expat, GNU
requirements:
  commands: [bcftools]
authors:
  - __merge__: /src/_authors/theodoro_gasperin.yaml
    roles: [author]

argument_groups:
  - name: Inputs
    arguments:
      - name: --input
        type: file
        description: |
          Input VCF/BCF file.
          
          The file to be normalized, left-aligned, and/or processed.
        required: true
        example: "input.vcf.gz"
    
  - name: Outputs
    arguments:
      - name: --output
        alternatives: [-o]
        direction: output
        type: file
        description: |
          Write output to a file.
          
          If not specified, output goes to standard output.
        required: true
        example: "normalized.vcf.gz"
         
  - name: Options
    arguments:
      - name: --atomize
        alternatives: [-a]
        type: boolean_true
        description: |
          Decompose complex variants (e.g., MNVs become consecutive SNVs).
          
          Breaks down complex variants into simpler components.

      - name: --atom_overlaps
        type: string
        choices: [".", "*"]
        description: |
          Use the star allele (*) for overlapping alleles or set to missing (.).
          
          **Options:**
          - `*`: Use star allele for overlaps (default)
          - `.`: Set overlapping alleles to missing
        example: "*"

      - name: --check_ref
        alternatives: [-c]
        type: string
        choices: ['e', 'w', 'x', 's']
        description: |
          Check REF alleles and exit (e), warn (w), exclude (x), or set (s) bad sites.
          
          **Options:**
          - `e`: exit on REF mismatch (default)
          - `w`: warn about REF mismatches
          - `x`: exclude sites with REF mismatches
          - `s`: set/fix REF mismatches
        example: "w"

      - name: --remove_duplicates_flag
        alternatives: [-D]
        type: boolean_true
        description: |
          Remove duplicate lines of the same type.
          
          Shorthand for --rm_dup exact.

      - name: --rm_dup
        alternatives: [-d]
        type: string
        choices: ['snps', 'indels', 'both', 'all', 'exact']
        description: |
          Remove duplicate snps|indels|both|all|exact.
          
          **Options:**
          - `snps`: Remove duplicate SNPs
          - `indels`: Remove duplicate indels
          - `both`: Remove duplicate SNPs and indels
          - `all`: Remove all duplicates
          - `exact`: Remove exact duplicates only
        example: "exact"

      - name: --exclude
        alternatives: [-e]
        type: string
        description: |
          Do not normalize records for which the expression is true.
          
          Uses bcftools expression syntax (see man page for details).
        example: "INFO/DP<10"

      - name: --fasta_ref
        alternatives: [-f]
        type: file
        description: |
          Reference sequence file.
          
          Required for checking REF alleles and left-alignment.
        example: "reference.fa"

      - name: --force
        type: boolean_true
        description: |
          Try to proceed even if malformed tags are encountered.
          
          **Warning:** Experimental feature, use at your own risk.

      - name: --gff_annot
        alternatives: [-g]
        type: file
        description: |
          Follow HGVS 3'rule and right-align variants in transcripts on the forward strand.
          
          Uses GFF annotation file for transcript information.
        example: "genes.gff"

      - name: --include
        alternatives: [-i]
        type: string
        description: |
          Normalize only records for which the expression is true.
          
          Uses bcftools expression syntax (see man page for details).
        example: "QUAL>=30"

      - name: --keep_sum
        type: string
        description: |
          Keep vector sum constant when splitting multiallelics.
          
          Comma-separated list of INFO tags (see github issue #360).
        example: "AC,AF"

      - name: --multiallelics
        alternatives: [-m]
        type: string
        choices: ['+snps', '+indels', '+both', '+any', '-snps', '-indels', '-both', '-any']
        description: |
          Split multiallelics (-) or join biallelics (+), type: snps|indels|both|any.
          
          **Options:**
          - `-both`: Split multiallelic sites (default)
          - `+both`: Join biallelic sites
          - Use `snps`, `indels`, `any` for specific variant types
        example: "-both"

      - name: --multi_overlaps
        type: string
        choices: ['0', '.']
        description: |
          Fill in the reference (0) or missing (.) allele when splitting multiallelics.
          
          **Options:**
          - `0`: Fill with reference allele (default)
          - `.`: Fill with missing allele
        example: "0"

      - name: --no_version
        type: boolean_true
        description: |
          Do not append version and command line to the header.
          
          Produces cleaner output headers.

      - name: --do_not_normalize
        alternatives: [-N]
        type: boolean_true
        description: |
          Do not normalize indels (with -m or -c s).
          
          Skips indel left-alignment and normalization.
      
      - name: --old_rec_tag
        type: string
        description: |
          Annotate modified records with INFO/STR indicating the original variant.
          
          Adds specified INFO tag to track original variants.
        example: "OLD_VARIANT"

      - name: --output_type
        alternatives: [-O]
        type: string
        choices: ['u', 'z', 'b', 'v']
        description: |
          Output type and compression level.
          
          **Options:**
          - `u`: uncompressed BCF
          - `b`: compressed BCF
          - `v`: uncompressed VCF (default)
          - `z`: compressed VCF (with optional compression level 0-9)
        example: "z"

      - name: --regions
        alternatives: [-r]
        type: string
        description: |
          Restrict to comma-separated list of regions.
          
          **Formats supported:** chr|chr:pos|chr:beg-end|chr:beg-[,…​]
        example: "chr20:1000000-2000000"

      - name: --regions_file
        alternatives: [-R]
        type: file
        description: |
          Restrict to regions listed in a file.
          
          Regions can be specified in VCF, BED, or tab-delimited format.
        example: "regions.bed"

      - name: --regions_overlap
        type: string
        choices: ['0', '1', '2']
        description: |
          Include if POS in the region (0), record overlaps (1), variant overlaps (2).
          
          **Options:**
          - `0`: POS inside region (default for -t/-T)
          - `1`: overlapping records included (default for -r/-R)
          - `2`: true overlapping variation only
        example: "1"

      - name: --strict_filter
        alternatives: [-s]
        type: boolean_true
        description: |
          When merging (-m+), merged site is PASS only if all sites being merged PASS.
          
          Stricter FILTER handling during multiallelic joining.

      - name: --sort
        alternatives: [-S]
        type: string
        choices: ['chr_pos', 'lex']
        description: |
          Sort order: chr_pos,lex.
          
          **Options:**
          - `chr_pos`: Sort by chromosome and position (default)
          - `lex`: Lexicographic sort
        example: "chr_pos"

      - name: --targets
        alternatives: [-t]
        type: string
        description: |
          Similar to --regions but streams rather than index-jumps.
          
          More efficient for processing many small regions.
        example: "chr20:1000000-2000000"

      - name: --targets_file
        alternatives: [-T]
        type: file
        description: |
          Similar to --regions_file but streams rather than index-jumps.
          
          More efficient for processing many regions from file.
        example: "targets.bed"

      - name: --targets_overlap
        type: string
        choices: ['0', '1', '2']
        description: |
          Include if POS in the region (0), record overlaps (1), variant overlaps (2).
          
          Similar to --regions_overlap but for streaming mode.
        example: "0"

      - name: --verbosity
        alternatives: [-v]
        type: integer
        description: |
          Verbosity level.
          
          Controls amount of diagnostic output.
        example: 1

      - name: --site_win
        alternatives: [-w]
        type: integer
        description: |
          Buffer for sorting lines which changed position during realignment.
          
          Larger values use more memory but handle more complex rearrangements.
        example: 1000

      - name: --write_index
        alternatives: [-W]
        type: string
        description: |
          Automatically index the output files.
          
          **Format:** Specify index format or use default.
        example: "tbi"

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/bcftools:1.22--h3a4d415_1
    setup:
      - type: docker
        run: |
          bcftools --version 2>&1 | head -1 | sed 's/bcftools /bcftools: /' > /var/software_versions.txt

runners:
  - type: executable
  - type: nextflow
