/vcf-variant-filtering

name: vcf-variant-filtering
description: "Guide to quality filtering raw VCF files before computing summary stats (Ts/Tv ratio, variant counts, AF distributions). Covers detecting raw VCFs via FILTER column and QUAL inspection, QUAL-based filtering with bcftools, Ts/Tv interpretation, and when NOT to filter. Read before any variant-level QC task. See bcftools-variant-manipulation for advanced filters, gatk-variant-calling for caller config, samtools-bam-processing for upstream alignment QC."
license: CC-BY-4.0

VCF Variant Filtering Guide

Overview

Raw VCF files produced by variant callers (GATK HaplotypeCaller, bcftools mpileup, DeepVariant, etc.) contain a mixture of true variants and artifacts from sequencing errors, alignment issues, and low-coverage regions. Computing summary statistics -- Ts/Tv ratio, variant counts, allele frequency distributions -- on unfiltered data yields unreliable results because false-positive calls disproportionately inflate transversion counts and depress the Ts/Tv ratio. This guide covers how to detect whether a VCF is raw, how to apply appropriate quality filters, when filtering is not appropriate, and how to interpret the resulting statistics correctly.

Key Concepts

VCF Quality Scores (QUAL Field)

The QUAL column in a VCF file represents the Phred-scaled probability that the variant site is polymorphic. A QUAL score of 30 means a 1-in-1000 chance the call is wrong; a QUAL of 20 means 1-in-100. Variant callers assign QUAL scores based on read evidence, base qualities, and mapping qualities. Low-QUAL variants (below 20-30) are enriched for sequencing errors and alignment artifacts. Filtering on QUAL is the simplest and most widely used first-pass quality control step.

Common QUAL thresholds and their interpretation:

| QUAL Score | Error Probability | Typical Use | |------------|------------------|-------------| | 10 | 1 in 10 | Very permissive; rarely appropriate for final calls | | 20 | 1 in 100 | Lenient filtering; useful for somatic calling with supporting evidence | | 30 | 1 in 1,000 | Standard default for germline variant filtering | | 50 | 1 in 100,000 | Stringent; used in clinical or high-confidence applications | | 100+ | Extremely low | Highly supported variants; may over-filter low-coverage regions |

For GATK-based workflows, VQSR or hard filtering on INFO annotations (QD, FS, MQ, etc.) may supplement or replace QUAL filtering. GATK's recommended hard filters for SNPs include QD < 2.0, FS > 60.0, MQ < 40.0, MQRankSum < -12.5, and ReadPosRankSum < -8.0.

Ts/Tv Ratio Significance

The transition-to-transversion (Ts/Tv) ratio is a key quality metric for variant call sets. Transitions (A<->G, C<->T) are chemically favored over transversions (all other substitutions) due to the molecular structure of nucleotide bases. Expected Ts/Tv values serve as benchmarks:

• Whole-genome sequencing (WGS): approximately 2.0-2.1
• Whole-exome sequencing (WES): approximately 2.8-3.3 (higher due to CpG enrichment in coding regions)
• Raw/unfiltered call sets: often 1.5-1.8 or lower

A Ts/Tv ratio significantly below the expected range indicates contamination by false-positive transversion calls, which are the hallmark of sequencing errors. After proper quality filtering, the Ts/Tv ratio should rise to the expected range for the assay type.

Raw vs Filtered VCFs

A "raw" VCF is the direct output of a variant caller before any quality filtering has been applied. A "filtered" VCF has had quality thresholds applied, either by hard filtering (QUAL, DP, QD, etc.) or by model-based filtering (GATK VQSR, CNN). Distinguishing between the two is critical because computing statistics on raw data without disclosure leads to incorrect conclusions.

Indicators that a VCF is raw or unfiltered:

• The filename contains "raw" (e.g., `sample_raw_variants.vcf`)
• The FILTER column contains only `.` (missing) for all records
• A large fraction of variants have QUAL scores below 30
• The Ts/Tv ratio is well below the expected range for the assay type

Indicators that a VCF has already been filtered:

• The FILTER column contains meaningful values (`PASS`, `LowQual`, `VQSRTrancheSNP99.90to100.00`)
• A filter command is recorded in the VCF header (`##FILTER=` and `##bcftools_viewCommand=` lines)

FILTER Column Semantics

The FILTER column in VCF format has specific semantics defined by the VCF specification:

• `.` (dot) -- filter status has not been applied; the variant is unassessed
• `PASS` -- the variant passed all filters
• Any other value -- the variant failed the named filter(s); multiple filters are semicolon-separated

A common misconception is that `.` means the variant passed. In reality, `.` means no filter has been evaluated, so the variant's quality is unknown. Another misconception is that `PASS` in every row means the file is unfiltered -- some callers (e.g., DeepVariant) mark all emitted variants as PASS because they only output high-confidence calls.

To inspect the FILTER column programmatically:

# Count occurrences of each FILTER value
bcftools query -f '%FILTER\n' input.vcf | sort | uniq -c | sort -rn | head

# Check if any non-'.' FILTER values exist
bcftools query -f '%FILTER\n' input.vcf | grep -v '^\.$' | head

Understanding the FILTER column is the first step in any VCF quality assessment. Always inspect it before deciding whether additional filtering is needed.

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: analysisGoal
    kind: required
    source: user
    ask: "What is the filtered call set for - a rare-disease search, a somatic variant list, a population study, or a genotyping panel?"
    default: null

  - id: D2
    param: filteringApproach
    kind: required
    source: user
    depends_on: [D1]
    ask: "Fixed hard thresholds, or a recalibration model trained on the cohort?"
    default: "hard filters; recalibration needs