name: bcftools_stats
namespace: bcftools
description: | 
  Parses VCF or BCF and produces a txt stats file which can be plotted using plot-vcfstats.
  When two files are given, the program generates separate stats for intersection
  and the complements. By default only sites are compared, -s/-S must given to include
  also sample columns.
keywords: [Stats, VCF, BCF]
links:
  homepage: https://samtools.github.io/bcftools/
  documentation: https://samtools.github.io/bcftools/bcftools.html#stats
  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
        multiple: true
        description: |
          Input VCF/BCF file(s). Maximum of two files can be provided.
          When two files are given, the program generates separate stats 
          for intersection and the complements.
        required: true
        example: input.vcf.gz
    
  - name: Outputs
    arguments:
      - name: --output
        alternatives: -o
        direction: output
        type: file
        description: |
          Write output to a file. The output is a text file which can be 
          plotted using plot-vcfstats.
        required: true
        example: stats.txt
         
  - name: Options
    arguments:
      - name: --af_bins
        type: string
        description: | 
          Allele frequency bins, a list of comma-separated bin values.
        example: "0.1,0.5,1"

      - name: --af_tag
        type: string
        description: | 
          Allele frequency tag to use, by default estimated from AN,AC or GT.
        example: "AF"

      - name: --collapse
        alternatives: -c
        type: string
        choices: [snps, indels, both, all, some, none]
        description: | 
          Treat as identical records with <snps|indels|both|all|some|none>.
        example: "snps"

      - name: --depth
        alternatives: -d
        type: string
        description: | 
          Depth distribution: min,max,bin size [0:200:1].
        example: "0,500,1"

      - name: --exclude
        alternatives: -e
        type: string
        description: | 
          Exclude sites for which the expression is true.
        example: "QUAL < 30"

      - name: --exons
        alternatives: -E
        type: file
        description: | 
          Tab-delimited file with exons for indel frameshifts statistics.
          The columns of the file are CHR, FROM, TO, with 1-based positions.
          The file should be BGZF-compressed and indexed with tabix.
        example: exons.bed.gz

      - name: --apply_filters
        alternatives: -f
        type: string
        description: | 
          Require at least one of the listed FILTER strings.
        example: "PASS,."

      - name: --fasta_ref
        alternatives: -F
        type: file
        description: | 
          Faidx indexed reference sequence file to determine INDEL context.
        example: reference.fa

      - name: --first_allele_only
        alternatives: ["--1st-allele-only"]
        type: boolean_true
        description: | 
          Include only 1st allele at multiallelic sites.

      - name: --include
        alternatives: -i
        type: string
        description: | 
          Select sites for which the expression is true.
        example: "QUAL >= 30"
      
      - name: --split_by_id
        alternatives: -I
        type: boolean_true
        description: | 
          Collect stats for sites with ID separately (known vs novel).

      - name: --regions
        alternatives: -r
        type: string
        description: | 
          Restrict to comma-separated list of regions.
        example: "chr20:1000000-2000000"

      - name: --regions_file
        alternatives: -R
        type: file
        description: | 
          Restrict to regions listed in a file.
        example: regions.bed

      - name: --regions_overlap
        type: string
        choices: [pos, record, variant, "0", "1", "2"]
        description: | 
          Include if POS in the region (pos), record overlaps (record), 
          variant overlaps (variant). Can also use numeric equivalents 0, 1, 2.

      - name: --samples
        alternatives: -s
        type: string
        description: | 
          List of samples for sample stats, "-" to include all samples.
        example: "sample1,sample2"

      - name: --samples_file
        alternatives: -S
        type: file
        description: | 
          File of samples to include.
        example: samples.txt

      - name: --targets
        alternatives: -t
        type: string
        description: | 
          Similar to regions, but streams rather than using index.
          Targets can be prefixed with "^" for logical complement.
        example: "chr20:1000000-2000000"
      
      - name: --targets_file
        alternatives: -T
        type: file
        description: | 
          Similar to regions_file but streams rather than index-jumps.
        example: targets.bed

      - name: --targets_overlap
        type: string
        choices: [pos, record, variant, "0", "1", "2"]
        description: | 
          Include if POS in the region (pos), record overlaps (record), 
          variant overlaps (variant). Can also use numeric equivalents 0, 1, 2.

      - name: --user_tstv
        alternatives: -u
        type: string
        description: | 
          Collect Ts/Tv stats for any tag using the given binning.
          Format is TAG[:min:max:n]. Default binning is [0:1:100].
        example: "QUAL:0:40:40"
      
      - name: --verbose 
        alternatives: -v
        type: boolean_true
        description: | 
          Produce verbose per-site and per-sample output.

resources:
  - type: bash_script
    path: script.sh

test_resources:
  - type: bash_script
    path: test.sh

engines:
  - type: docker
    image: quay.io/biocontainers/bcftools:1.22--h3a4d415_1
    setup:
      - type: docker
        run: |
          bcftools --version | head -1 | sed 's/bcftools /bcftools: /' > /var/software_versions.txt

runners:
  - type: executable
  - type: nextflow

