Skip to content

Variant Info

afquery variant-info returns the list of samples carrying a specific variant, together with each sample's metadata: sex, sequencing technology, phenotype codes, genotype (het/hom/hemi), and FILTER status (PASS/FAIL).

This avoids the need to re-query raw VCF files when inspecting individual variant carriers.


Basic usage

afquery variant-info --db ./db/ --locus chr1:925952

Tip

variant-info is the natural next step after query β€” once you find a variant of interest, use it to see which specific samples carry it.

Carriers match the counts reported by query

variant-info lists only samples whose capture regions cover the position, the same eligible set query uses. A WES sample with a call outside its own BED is not counted in AN, AC or the genotype tallies, and is not listed here either. Each carrier is labelled with the class query counts it in, following the sample's ploidy at the position rather than how the VCF wrote the genotype, so the number of het, hom, hemi and alt carriers equals N_HET, N_HOM_ALT, N_HEMI and N_FAIL for the same allele and filters, on every chromosome.

By default all samples are queried and results are printed as an aligned text table:

sample_id  sample_name  sex     tech       phenotypes    genotype  filter
---------  -----------  ------  ---------  ------------  --------  ------
3          P003         male    WGS        E11.9,J45     het       PASS
17         P017         female  WES_kit_A  E11.9         hom       PASS
42         P042         male    WGS        I10           alt       FAIL

Filtering to a specific allele

When multiple alleles exist at the same position, use --ref and --alt to restrict to one:

afquery variant-info --db ./db/ --locus chr17:41245466 --ref A --alt T

Note

Without --ref/--alt, carriers for all alleles at the locus are returned and a warning is emitted if more than one allele is found. Specify both flags to disambiguate at multi-allelic sites.


Sample filters

variant-info accepts the same sample filters as query:

# Only female carriers
afquery variant-info --db ./db/ --locus chr1:925952 --sex female

# Only carriers with phenotype E11.9
afquery variant-info --db ./db/ --locus chr1:925952 --phenotype E11.9

# Exclude phenotype I10
afquery variant-info --db ./db/ --locus chr1:925952 --phenotype ^I10

# Restrict to WGS samples
afquery variant-info --db ./db/ --locus chr1:925952 --tech WGS

# Combine filters
afquery variant-info --db ./db/ --locus chr1:925952 \
  --sex female --phenotype E11.9 --tech WGS,WES_kit_A

See Sample Filtering for the full filter syntax.


Output formats

TSV

Machine-readable tab-separated output, suitable for downstream processing:

afquery variant-info --db ./db/ --locus chr1:925952 --format tsv > carriers.tsv
sample_id   sample_name sex tech    phenotypes  genotype    filter
3   P003    male    WGS E11.9,J45   het PASS
17  P017    female  WES_kit_A   E11.9   hom PASS
42  P042    male    WGS I10 alt FAIL

JSON

Structured output with variant metadata and a sample list:

afquery variant-info --db ./db/ --locus chr1:925952 --format json
{
  "variant": {
    "chrom": "chr1",
    "pos": 925952,
    "ref": ".",
    "alt": "."
  },
  "samples": [
    {
      "sample_id": 3,
      "sample_name": "P003",
      "sex": "male",
      "tech": "WGS",
      "phenotypes": ["E11.9", "J45"],
      "genotype": "het",
      "filter": "PASS"
    },
    {
      "sample_id": 42,
      "sample_name": "P042",
      "sex": "male",
      "tech": "WGS",
      "phenotypes": ["I10"],
      "genotype": "alt",
      "filter": "FAIL"
    }
  ]
}

When --ref and --alt are specified, the variant block contains the actual alleles. Otherwise, "." is used as a placeholder.


Genotype values

Value Meaning
het Heterozygous carrier (diploid 0/1), FILTER=PASS. Counted in N_HET
hom Homozygous alt carrier (diploid 1/1), FILTER=PASS. On chrM every carrier is hom, whatever its GT: AFQuery records no heteroplasmy. Counted in N_HOM_ALT
hemi Hemizygous carrier, FILTER=PASS: a male carrying the allele on chrX outside the PARs or on chrY, where he has a single copy (GT 1, or 1/1 written diploid). Counted in N_HEMI
alt Failed call for any allele at this position — FILTER≠PASS, or a genotype inconsistent with the sample's ploidy such as 0/1 in a male on chrX non-PAR; genotype unknown. Listed for every allele of the position, as in N_FAIL
no_coverage Sample's tech lacks coverage evidence at this position; not a carrier. Only appears when a coverage-evidence filter (--min-pass, --min-observed, --min-quality-evidence, or build-time --min-covered) is active. The FILTER column is empty (text/tsv) or null (JSON) β€” PASS/FAIL does not apply because there is no call. See Coverage Evidence.

All options

Option Default Description
--db required Path to database directory
--locus required CHROM:POS (e.g. chr1:925952)
--ref β€” Filter to specific reference allele
--alt β€” Filter to specific alternate allele
--phenotype all Include phenotype (repeatable; ^CODE excludes)
--sex both male, female, or both
--tech all Include technology (repeatable; ^NAME excludes)
--format text text, tsv, or json
--no-warn off Suppress AfqueryWarning messages

See also CLI Reference β†’ variant-info.


Next Steps