name: bcftools_concat
namespace: bcftools
description: | 
  Concatenate or combine VCF/BCF files. All source files must have the same sample
  columns appearing in the same order. The program can be used, for example, to
  concatenate chromosome VCFs into one VCF, or combine a SNP VCF and an indel
  VCF into one. The input files must be sorted by chr and position. The files
  must be given in the correct order to produce sorted VCF on output unless
  the -a, --allow-overlaps option is specified. With the --naive option, the files
  are concatenated without being recompressed, which is very fast.
keywords: [Concatenate, VCF, BCF]
links:
  homepage: https://samtools.github.io/bcftools/
  documentation: https://samtools.github.io/bcftools/bcftools.html#concat
  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
        alternatives: [-i]
        type: file
        multiple: true
        description: |
          Input VCF/BCF files to concatenate.
          
          All source files must have the same sample columns appearing in 
          the same order. Files must be sorted by chr and position.
        example: "input1.vcf.gz input2.vcf.gz"
      
      - name: --file_list
        alternatives: [-f]
        type: file
        description: |
          Read the list of VCF/BCF files from a file, one file name per line.
          
          Alternative to providing multiple --input files.
        example: "files_list.txt"
    
  - 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: "concatenated.vcf.gz"
         
  - name: Options
    arguments:
      - name: --allow_overlaps
        alternatives: [-a]
        type: boolean_true
        description: |
          First coordinate of the next file can precede last record of the current file.
          
          Allows overlapping records between files during concatenation.
      
      - name: --compact_ps
        alternatives: [-c]
        type: boolean_true
        description: |
          Do not output PS tag at each site, only at the start of a new phase set block.
          
          Reduces output size for phased data.
      
      - name: --rm_dups
        alternatives: [-d]
        type: string
        choices: ['snps', 'indels', 'both', 'all', 'exact']
        description: |
          Output duplicate records present in multiple files only once.
          
          **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: --remove_duplicates
        alternatives: [-D]
        type: boolean_true
        description: |
          Alias for --rm_dups exact.
          
          Remove exact duplicate records present in multiple files.
      
      - name: --drop_genotypes
        alternatives: [-G]
        type: boolean_true
        description: |
          Drop individual genotype information.
          
          Removes all sample-specific data from output.
          
      - name: --ligate
        alternatives: [-l]
        type: boolean_true
        description: |
          Ligate phased VCFs by matching phase at overlapping haplotypes.
          
          Connects phase information across files.
      
      - name: --ligate_force
        type: boolean_true
        description: |
          Ligate even non-overlapping chunks, keep all sites.
          
          Forces ligation without requiring overlap validation.
      
      - name: --ligate_warn
        type: boolean_true
        description: |
          Drop sites in imperfect overlaps.
          
          Conservative ligation that removes problematic sites.

      - name: --no_version
        type: boolean_true
        description: |
          Do not append version and command line to the header.
          
          Produces cleaner output headers.
        
      - name: --naive
        alternatives: [-n]
        type: boolean_true
        description: |
          Concatenate files without recompression.
          
          Very fast operation with header compatibility check.
      
      - name: --naive_force
        type: boolean_true
        description: |
          Same as --naive, but header compatibility is not checked.
          
          **Warning:** Dangerous option, use with caution.

      - 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
          - `z`: compressed VCF (with optional compression level 0-9)
        example: "z"
    
      - name: --min_pq
        alternatives: [-q]
        type: integer
        description: |
          Break phase set if phasing quality is lower than specified value.
          
          Only relevant when working with phased data.
        example: 30

      - 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: --verbosity
        alternatives: [-v]
        type: integer
        description: |
          Set verbosity level.
          
          Controls amount of diagnostic output.
        example: 1

      - 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