Annotate a VCF
afquery annotate adds allele frequency information to an existing VCF file as INFO fields. It queries each variant in the VCF against the database and writes results inline.
Basic Usage
Added INFO Fields
| Field | Type | Number | Description |
|---|---|---|---|
AFQUERY_AC |
Integer | A (per ALT) | Allele count in eligible samples |
AFQUERY_AN |
Integer | 1 (per site) | Allele number (total alleles examined, excluding samples in AFQUERY_N_FAIL) |
AFQUERY_AF |
Float | A (per ALT) | Allele frequency (AC / AN); . when AFQUERY_AN=0 |
AFQUERY_N_HET |
Integer | A (per ALT) | Heterozygous sample count (diploid genotypes) |
AFQUERY_N_HOM_ALT |
Integer | A (per ALT) | Homozygous alt sample count (diploid genotypes); on chrM, every carrier |
AFQUERY_N_HEMI |
Integer | A (per ALT) | Hemizygous carrier count: males carrying the allele on chrX outside the PARs or on chrY. 0 on autosomes, chrX PARs and chrM |
AFQUERY_N_HOM_REF |
Integer | A (per ALT) | Count of samples carrying only the reference allele (homozygous, or hemizygous where haploid), excluding carriers of other ALT alleles at the position (including alleles stored in the database but absent from the input record) |
AFQUERY_N_FAIL |
Integer | 1 (per site) | Eligible samples with a failed call (FILTER≠PASS, or a genotype inconsistent with the sample's ploidy) for any ALT allele at the position, each counted once. Excluded from AC and AN. Mutually exclusive with N_HET/N_HOM_ALT/N_HEMI/N_HOM_REF. |
AFQUERY_N_NO_COVERAGE |
Integer | A (per ALT) | Eligible samples whose tech lacks coverage evidence at this position. Excluded from N_HOM_REF; still counted in AN. Always 0 unless a coverage-evidence filter is active. See Coverage Evidence. |
Multi-allelic sites
Number=A fields have one value per ALT allele (comma-separated for multi-allelic sites). Number=1 fields are shared across all ALT alleles at the same position.
Sample Filtering
Annotate with a specific subgroup:
afquery annotate \
--db ./db/ \
--input variants.vcf \
--output annotated.vcf \
--phenotype E11.9 \
--sex female \
--tech wgs
The INFO fields will reflect AF computed only over the filtered sample set. This allows generating population-specific frequency tracks.
Parallelism
Annotation runs in parallel across variants. By default, all available CPU cores are used:
For large VCFs (100K+ variants), set --threads to the number of available cores.
Using Annotated Output
BCFtools
Filter variants with high AF:
Extract specific fields:
Python (pysam / cyvcf2)
import cyvcf2
vcf = cyvcf2.VCF("annotated.vcf")
for variant in vcf:
ac = variant.INFO.get("AFQUERY_AC")
an = variant.INFO.get("AFQUERY_AN")
af = variant.INFO.get("AFQUERY_AF")
print(f"{variant.CHROM}:{variant.POS} AC={ac} AN={an} AF={af}")
R (VariantAnnotation)
Full Option Reference
Next Steps
- Clinical Prioritization — filter annotated VCFs to retain only rare local variants
- Sample Filtering — annotate using subgroup-specific AF (phenotype, sex, tech)
- Understanding Output — what AFQUERY_AF/AC/AN/N_FAIL fields mean