fix: multi-allelic statistics and capture filtering in variant-info

[dlopez-bioinfo]

Summary

Three independent problems around multi-allelic sites and capture regions, reported on the CSVS hs37d5 database.

1. variant-info listed carriers outside their capture BED

variant_info() intersected the per-variant bitmaps with the sample filter only, so a sample with a call outside its own BED was listed as a carrier while query() excluded it from AC, AN and the genotype tallies. It now uses the same capture- and ploidy-aware eligible set as query().

On afquery_db_hs37d5 this accounts for every mismatch reported:

locus	before (variant-info)	after	query
1:6508625 A>G	120 het / 8 hom / 7 alt	95 / 7 / 0	N_HET=95, N_HOM_ALT=7, N_FAIL=0
13:44995309 G>A	218 het / 77 hom / 4 alt	218 / 73 / 1	218, 73, 1
13:44995309 G>T	35 het / 2 hom	34 / 2	34, 2

Behaviour change: the guide previously described the extra off-target carriers as expected; it is rewritten, and the debugging table no longer relies on that difference.

2. N_HOM_REF counted carriers of other alleles at multi-allelic sites

N_HOM_REF was the residual n_eligible - N_HET - N_HOM_ALT - N_FAIL - N_NO_COVERAGE. The eligible set depends only on the position, so at a site with several ALT alleles every carrier of another allele was counted as hom-ref for this one. The tallies for an allele now leave those samples out.

• Invariant change: at a biallelic site the five categories still add up to n_eligible. At a multi-allelic site they fall short by exactly the number of eligible samples carrying only another allele. AC, AN and AF are not affected. Documentation updated.
• Coverage evidence per position: --min-pass, --min-observed and --min-quality-evidence now count calls for any allele at the position, and a sample with such a call is never reported as N_NO_COVERAGE.
• The per-allele computation, previously repeated in query, region, batch, dump and annotate, now lives in QueryEngine._variant_stats. annotate also excludes carriers of stored alleles when the requested allele is absent from the database.
• The test oracle had the same residual and is corrected.
• Known limitation: the build-time --min-covered gate (filtered_bitmap) is still evaluated per allele. Carriers of other alleles are removed from it at query time, but at a multi-allelic site a rare allele's row can still report true hom-ref samples as N_NO_COVERAGE while the common allele's row counts them as hom-ref. Making it per position requires rebuilding the database.

At 13:44995309 N_HOM_REF goes from 165 (G>A) / 421 (G>T) to 141 for both, the number of G/G samples: 457 eligible minus the 316 carrying A, T or both (12 samples carry both). The commit message for this change says 36 samples were misclassified for G>A; the correct figure is 24, because the 12 samples carrying both alleles were already counted as carriers of A.

3. normalize_vcf.sh did not split multi-allelic records

bcftools norm ran without -m, and with -d passed twice; the effective -d both treats two different indels at one position as duplicates. Now -m -both -d exact. bcftools refuses that combination before 1.20 (checked with 1.18 and 1.19), so the script checks the version. VCFs normalized with the old script need re-normalizing and the database rebuilding; documented in the preprocessing guide.

Closes #39

Validation

• Full suite passes (618 tests). The regression tests for each fix fail on master.
• New tests/test_multiallelic.py: point, region, batch (one allele requested), batch-multi, dump, annotate, variant-info and --min-pass at a multi-allelic site. New oracle cohort with a 1/2 carrier, partial capture and a FILTER failure.
• Read-only comparison of master against this branch on afquery_db_hs37d5, whole chr22 (585,928 rows, 116,802 at multi-allelic positions):
  • default filters: no biallelic row changes; only N_HOM_REF changes, on 114,232 multi-allelic rows; the invariant holds on every row;
  • --min-pass 1: no biallelic row changes; AC/AN unchanged; N_NO_COVERAGE drops on 2,292 multi-allelic rows.
• Full-chromosome region query: 15.8 s on master, 18.1 s here (allele pooling at multi-allelic positions).
• normalize_vcf.sh run with bcftools 1.20 and 1.24 on the 2:136592357 record: two biallelic records, CAAAAAAA>C and C>CAAAAA, none dropped. Clear error with 1.18 and 1.19.
• mkdocs build --strict passes.

No database rebuild is needed for fixes 1 and 2; they apply at query time.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.07843% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.40%. Comparing base (313c4c7) to head (5629bf6).

Files with missing lines	Patch %	Lines
src/afquery/query.py	94.87%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #40      +/-   ##
==========================================
+ Coverage   88.69%   89.40%   +0.71%     
==========================================
  Files          22       22              
  Lines        3077     3077              
  Branches      482      488       +6     
==========================================
+ Hits         2729     2751      +22     
+ Misses        229      207      -22     
  Partials      119      119              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.