[meta]
name = "gatk"
category = "variant-calling"
description = "Genome Analysis Toolkit — best-practice variant discovery pipeline for germline and somatic variants"
tags = ["variant-calling", "snp", "indel", "germline", "somatic", "gatk", "best-practices"]
author = "oxo-call built-in"
source_url = "https://gatk.broadinstitute.org/hc/en-us"

[context]
concepts = [
    "GATK is invoked as 'gatk <tool>' (e.g., 'gatk HaplotypeCaller'); each tool has many options.",
    "GATK requires sorted, duplicate-marked BAM with a read group (@RG) — use MarkDuplicates before variant calling.",
    "The reference FASTA must be indexed with 'samtools faidx ref.fa' and have a sequence dictionary 'gatk CreateSequenceDictionary -R ref.fa'.",
    "HaplotypeCaller: germline variant calling; Mutect2: somatic variant calling; GenotypeGVCFs: joint genotyping.",
    "The GVCF workflow for cohort studies: HaplotypeCaller -ERC GVCF → GenomicsDBImport → GenotypeGVCFs.",
    "VQSR (VariantQualityScoreRecalibration) is preferred over hard filtering for large cohorts (>30 samples).",
    "For small cohorts, use hard filtering: SNPs: QD<2, FS>60, MQ<40; Indels: QD<2, FS>200.",
]

pitfalls = [
    "GATK requires a sequence dictionary (.dict file) alongside the reference FASTA — run CreateSequenceDictionary first.",
    "HaplotypeCaller needs read groups in the BAM; if missing, add with AddOrReplaceReadGroups first.",
    "Mutect2 somatic calling requires a matched normal sample with -I normal.bam -normal normal_sample_name.",
    "The --tmp-dir argument should point to a large temporary directory — GATK creates huge temp files.",
    "GATK4 uses Java 17+ by default; the gatk wrapper script handles this but the JAR must be executable.",
    "For WGS, always provide --intervals chr1 chr2 ... to parallelize; omitting it runs on the entire genome sequentially.",
]

[[examples]]
task = "call germline variants from a BAM file using HaplotypeCaller"
args = "HaplotypeCaller -R reference.fa -I sorted_markdup.bam -O output.g.vcf.gz -ERC GVCF"
explanation = "-ERC GVCF creates a GVCF for later joint genotyping; needed for multi-sample workflows"

[[examples]]
task = "genotype a single sample directly (not GVCF mode)"
args = "HaplotypeCaller -R reference.fa -I sorted_markdup.bam -O variants.vcf.gz"
explanation = "without -ERC GVCF, outputs a standard VCF directly; suitable for single-sample projects"

[[examples]]
task = "mark PCR duplicates in a BAM file"
args = "MarkDuplicates -I input.bam -O markdup.bam -M metrics.txt"
explanation = "removes/marks PCR duplicates; -M writes duplicate metrics; required before HaplotypeCaller"

[[examples]]
task = "call somatic mutations with Mutect2 using matched normal"
args = "Mutect2 -R reference.fa -I tumor.bam -I normal.bam -normal normal_sample_name -O somatic.vcf.gz"
explanation = "for somatic calling; -normal identifies which BAM is the matched normal"

[[examples]]
task = "filter Mutect2 variants with FilterMutectCalls"
args = "FilterMutectCalls -R reference.fa -V somatic.vcf.gz -O filtered_somatic.vcf.gz"
explanation = "applies filters to Mutect2 raw calls; variants PASS the filter or are tagged with a filter name"

[[examples]]
task = "create a sequence dictionary for a reference FASTA"
args = "CreateSequenceDictionary -R reference.fa"
explanation = "creates reference.dict in the same directory; required by HaplotypeCaller and other tools"

[[examples]]
task = "add read group to a BAM file (required before GATK variant calling)"
args = "AddOrReplaceReadGroups -I input.bam -O output_rg.bam -RGID sample1 -RGLB lib1 -RGPL ILLUMINA -RGPU unit1 -RGSM sample1"
explanation = "all four -RG fields are required; RGSM is the sample name used in the VCF"
